@c1m-public/control-client 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# `@c1m-public/control-client`
+
+Typed, server-side transport for C1M control-plane APIs. It exposes platform
+channel operations and workspace-owner channel operations without owning a
+host application's cookie, session, support-mode, geo, or forwarded-header
+policy.
+
+```ts
+import { createControlClient } from "@c1m-public/control-client/next";
+
+const control = createControlClient({
+  baseUrl: process.env.C1M_API_URL!,
+  getAccessToken: async () => (await resolveSession())?.token,
+  getHeaders: buildForwardedRequestHeaders,
+});
+
+const fleet = await control.platform.channels.list({ status: "active" });
+const owned = await control
+  .workspace({ saasApp: "quickprint", workspaceId: "workspace-id" })
+  .channels.list();
+```
+
+The npm package is public, but it contains no credentials and grants no access.
+Authorization remains enforced by C1M at the platform/operator or
+workspace-owner boundary. Never import the package into browser components or
+place access tokens in public environment variables.
+
+All requests are `no-store`; only GET requests retry transient failures. The
+access token and forwarded headers are resolved for every call so server
+request state cannot leak between users. Observations contain bounded operation
+metadata and never include paths, credentials, headers, bodies, tenant IDs, or
+workspace IDs.
+
+## Release
+
+Publish `0.1.0` once manually to create the npm package. Then configure its npm
+Trusted Publisher for GitHub repository `cloud1mediaLtd/mml-js`, workflow
+`publish-control-client.yml`, and push tags named `control-client-vX.Y.Z`.

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+export type * from "./types.js";
+import type { ChannelFilters, ChannelMint, ChannelWebhook, ChannelWebhookDelivery, PlatformChannel, PlatformChannelDetail, WebhookPage, WebhookSecret, WebhookWrite, WorkspaceChannel } from "./types.js";
+export type ControlOperation = `platform.channels.${string}` | `workspace.channels.${string}`;
+export type ControlRequestOutcome = "success" | "api_error" | "network_error" | "timeout" | "invalid_response";
+export interface ControlRequestObservation {
+    operation: ControlOperation;
+    method: string;
+    outcome: ControlRequestOutcome;
+    status: number;
+    requestId: string;
+    durationMs: number;
+    attempts: number;
+}
+export interface CreateControlClientOptions {
+    baseUrl: string;
+    getAccessToken: () => Promise<string | null | undefined>;
+    getHeaders?: () => Promise<HeadersInit | undefined>;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    retryAttempts?: number;
+    observe?: (event: ControlRequestObservation) => void;
+}
+export declare class ControlAPIError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string;
+    constructor(message: string, status: number, code: string, requestId: string);
+}
+export declare function createControlClient(options: CreateControlClientOptions): {
+    readonly platform: {
+        readonly channels: {
+            readonly list: (filters?: ChannelFilters) => Promise<{
+                items: PlatformChannel[];
+                next_cursor?: string;
+                has_more: boolean;
+            }>;
+            readonly get: (id: string) => Promise<PlatformChannelDetail>;
+            readonly create: (input: {
+                saas_app: string;
+                workspace_id: string;
+                name: string;
+                token_name: string;
+                site_url?: string;
+                reason: string;
+                confirm: boolean;
+            }) => Promise<ChannelMint<PlatformChannel>>;
+            readonly update: (id: string, input: {
+                status: "active" | "disabled";
+                reason: string;
+                confirm: boolean;
+            }) => Promise<PlatformChannel>;
+            readonly tokens: {
+                readonly mint: (channelId: string, input: {
+                    name: string;
+                    reason: string;
+                    confirm: boolean;
+                }) => Promise<ChannelMint<PlatformChannel>>;
+                readonly revoke: (channelId: string, tokenId: string, input: {
+                    reason: string;
+                    confirm: boolean;
+                }) => Promise<void>;
+            };
+            readonly webhooks: {
+                readonly fleet: (filters?: ChannelFilters) => Promise<WebhookPage>;
+                readonly list: (channelId: string) => Promise<WebhookPage>;
+                readonly create: (channelId: string, input: WebhookWrite) => Promise<WebhookSecret>;
+                readonly update: (channelId: string, webhookId: string, input: WebhookWrite) => Promise<ChannelWebhook>;
+                readonly delete: (channelId: string, webhookId: string, input: {
+                    reason: string;
+                    confirm: boolean;
+                }) => Promise<void>;
+                readonly revealSecret: (channelId: string, webhookId: string, input: {
+                    reason: string;
+                    confirm: boolean;
+                }) => Promise<WebhookSecret>;
+                readonly deliveries: (channelId: string, webhookId: string, cursor?: string) => Promise<{
+                    items: ChannelWebhookDelivery[];
+                    next_cursor?: string;
+                    has_more: boolean;
+                }>;
+                readonly replay: (channelId: string, webhookId: string, deliveryId: string, input: {
+                    reason: string;
+                    confirm: boolean;
+                }) => Promise<void>;
+            };
+        };
+    };
+    readonly workspace: (identity: {
+        saasApp: string;
+        workspaceId: string;
+    }) => {
+        readonly channels: {
+            readonly list: () => Promise<WorkspaceChannel[]>;
+            readonly create: (input: {
+                name: string;
+                token_name: string;
+                site_url?: string;
+            }) => Promise<ChannelMint<WorkspaceChannel>>;
+            readonly update: (channelId: string, input: {
+                status: "active" | "disabled";
+                site_url?: string;
+            }) => Promise<WorkspaceChannel>;
+            readonly tokens: {
+                readonly mint: (channelId: string, input: {
+                    name: string;
+                }) => Promise<ChannelMint<WorkspaceChannel>>;
+                readonly revoke: (channelId: string, tokenId: string) => Promise<void>;
+            };
+            readonly webhooks: {
+                readonly list: (channelId: string) => Promise<WebhookPage>;
+                readonly create: (channelId: string, input: WebhookWrite) => Promise<WebhookSecret>;
+                readonly update: (channelId: string, webhookId: string, input: WebhookWrite) => Promise<ChannelWebhook>;
+                readonly delete: (channelId: string, webhookId: string) => Promise<void>;
+                readonly revealSecret: (channelId: string, webhookId: string) => Promise<WebhookSecret>;
+                readonly deliveries: (channelId: string, webhookId: string, cursor?: string) => Promise<{
+                    items: ChannelWebhookDelivery[];
+                    next_cursor?: string;
+                    has_more: boolean;
+                }>;
+                readonly replay: (channelId: string, webhookId: string, deliveryId: string) => Promise<void>;
+                readonly test: (channelId: string, webhookId: string) => Promise<void>;
+            };
+        };
+    };
+};

package/dist/index.js

@@ -0,0 +1,157 @@
+const RETRYABLE = new Set([429, 502, 503, 504]);
+export class ControlAPIError extends Error {
+    status;
+    code;
+    requestId;
+    constructor(message, status, code, requestId) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+        this.name = "ControlAPIError";
+    }
+}
+function required(value, label) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new Error(`${label} is required`);
+    return normalized;
+}
+function segment(value) {
+    return encodeURIComponent(required(value, "path value"));
+}
+function query(path, values) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(values)) {
+        if (value !== undefined && String(value).trim())
+            params.set(key, String(value).trim());
+    }
+    return params.size ? `${path}?${params}` : path;
+}
+export function createControlClient(options) {
+    const baseUrl = required(options.baseUrl, "baseUrl").replace(/\/+$/, "");
+    const fetcher = options.fetch ?? globalThis.fetch;
+    if (!fetcher)
+        throw new Error("fetch implementation is required");
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const retryAttempts = options.retryAttempts ?? 1;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new Error("timeoutMs must be positive");
+    if (!Number.isSafeInteger(retryAttempts) || retryAttempts < 0)
+        throw new Error("retryAttempts must be a non-negative integer");
+    async function request(operation, path, init = {}) {
+        const method = (init.method ?? "GET").toUpperCase();
+        const started = Date.now();
+        let attempts = 0;
+        let status = 0;
+        let requestId = "";
+        let outcome = "network_error";
+        try {
+            const token = required((await options.getAccessToken()) ?? "", "access token");
+            const headers = new Headers(await options.getHeaders?.());
+            new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+            headers.set("Authorization", `Bearer ${token}`);
+            if (init.body !== undefined && !headers.has("Content-Type"))
+                headers.set("Content-Type", "application/json");
+            let response;
+            for (let attempt = 0; attempt <= (method === "GET" ? retryAttempts : 0); attempt += 1) {
+                attempts = attempt + 1;
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), timeoutMs);
+                try {
+                    response = await fetcher(`${baseUrl}${path}`, { ...init, method, headers, cache: "no-store", signal: controller.signal });
+                }
+                catch {
+                    if (controller.signal.aborted) {
+                        outcome = "timeout";
+                        throw new ControlAPIError("Control API request timed out", 0, "control_request_timeout", "");
+                    }
+                    outcome = "network_error";
+                    throw new ControlAPIError("Control API request failed", 0, "control_network_error", "");
+                }
+                finally {
+                    clearTimeout(timeout);
+                }
+                if (!RETRYABLE.has(response.status) || attempt === retryAttempts || method !== "GET")
+                    break;
+            }
+            if (!response)
+                throw new ControlAPIError("Control API request failed", 0, "control_network_error", "");
+            status = response.status;
+            requestId = response.headers.get("X-Request-ID") ?? "";
+            const text = await response.text();
+            let payload;
+            try {
+                payload = text ? JSON.parse(text) : undefined;
+            }
+            catch {
+                outcome = "invalid_response";
+                throw new ControlAPIError("Control API response was not valid JSON", status, "invalid_control_response", requestId);
+            }
+            if (!response.ok) {
+                const error = payload;
+                requestId = typeof error?.request_id === "string" ? error.request_id : requestId;
+                outcome = "api_error";
+                throw new ControlAPIError(typeof error?.message === "string" ? error.message : "Control API request failed", status, typeof error?.code === "string" ? error.code : "control_request_failed", requestId);
+            }
+            outcome = "success";
+            return payload;
+        }
+        finally {
+            try {
+                options.observe?.({ operation, method, outcome, status, requestId, durationMs: Math.max(0, Date.now() - started), attempts });
+            }
+            catch { }
+        }
+    }
+    const platformBase = "/api/v1/platform/channels";
+    const platformChannel = (id) => `${platformBase}/${segment(id)}`;
+    const platformWebhook = (channelId, webhookId) => `${platformChannel(channelId)}/webhooks/${segment(webhookId)}`;
+    const platform = {
+        channels: {
+            list: (filters = {}) => request("platform.channels.list", query(platformBase, filters)),
+            get: (id) => request("platform.channels.get", platformChannel(id)),
+            create: (input) => request("platform.channels.create", platformBase, { method: "POST", body: JSON.stringify(input) }),
+            update: (id, input) => request("platform.channels.update", platformChannel(id), { method: "PATCH", body: JSON.stringify(input) }),
+            tokens: {
+                mint: (channelId, input) => request("platform.channels.tokens.mint", `${platformChannel(channelId)}/tokens`, { method: "POST", body: JSON.stringify(input) }),
+                revoke: (channelId, tokenId, input) => request("platform.channels.tokens.revoke", `${platformChannel(channelId)}/tokens/${segment(tokenId)}/revoke`, { method: "POST", body: JSON.stringify(input) }),
+            },
+            webhooks: {
+                fleet: (filters = {}) => request("platform.channels.webhooks.fleet", query(`${platformBase}/webhooks`, filters)),
+                list: (channelId) => request("platform.channels.webhooks.list", `${platformChannel(channelId)}/webhooks`),
+                create: (channelId, input) => request("platform.channels.webhooks.create", `${platformChannel(channelId)}/webhooks`, { method: "POST", body: JSON.stringify(input) }),
+                update: (channelId, webhookId, input) => request("platform.channels.webhooks.update", platformWebhook(channelId, webhookId), { method: "PATCH", body: JSON.stringify(input) }),
+                delete: (channelId, webhookId, input) => request("platform.channels.webhooks.delete", platformWebhook(channelId, webhookId), { method: "DELETE", body: JSON.stringify(input) }),
+                revealSecret: (channelId, webhookId, input) => request("platform.channels.webhooks.secret.reveal", `${platformWebhook(channelId, webhookId)}/secret/reveal`, { method: "POST", body: JSON.stringify(input) }),
+                deliveries: (channelId, webhookId, cursor) => request("platform.channels.webhooks.deliveries", query(`${platformWebhook(channelId, webhookId)}/deliveries`, { cursor })),
+                replay: (channelId, webhookId, deliveryId, input) => request("platform.channels.webhooks.replay", `${platformWebhook(channelId, webhookId)}/deliveries/${segment(deliveryId)}/replay`, { method: "POST", body: JSON.stringify(input) }),
+            },
+        },
+    };
+    function workspace(identity) {
+        const base = `/api/v1/platform/saas/${segment(identity.saasApp)}/workspaces/${segment(identity.workspaceId)}/channels`;
+        const channel = (id) => `${base}/${segment(id)}`;
+        const webhook = (channelId, webhookId) => `${channel(channelId)}/webhooks/${segment(webhookId)}`;
+        return { channels: {
+                list: async () => (await request("workspace.channels.list", base)).items ?? [],
+                create: (input) => request("workspace.channels.create", base, { method: "POST", body: JSON.stringify(input) }),
+                update: (channelId, input) => request("workspace.channels.update", channel(channelId), { method: "PATCH", body: JSON.stringify(input) }),
+                tokens: {
+                    mint: (channelId, input) => request("workspace.channels.tokens.mint", `${channel(channelId)}/tokens`, { method: "POST", body: JSON.stringify(input) }),
+                    revoke: (channelId, tokenId) => request("workspace.channels.tokens.revoke", `${channel(channelId)}/tokens/${segment(tokenId)}`, { method: "DELETE" }),
+                },
+                webhooks: {
+                    list: (channelId) => request("workspace.channels.webhooks.list", `${channel(channelId)}/webhooks`),
+                    create: (channelId, input) => request("workspace.channels.webhooks.create", `${channel(channelId)}/webhooks`, { method: "POST", body: JSON.stringify(input) }),
+                    update: (channelId, webhookId, input) => request("workspace.channels.webhooks.update", webhook(channelId, webhookId), { method: "PATCH", body: JSON.stringify(input) }),
+                    delete: (channelId, webhookId) => request("workspace.channels.webhooks.delete", webhook(channelId, webhookId), { method: "DELETE" }),
+                    revealSecret: (channelId, webhookId) => request("workspace.channels.webhooks.secret.reveal", `${webhook(channelId, webhookId)}/secret`),
+                    deliveries: (channelId, webhookId, cursor) => request("workspace.channels.webhooks.deliveries", query(`${webhook(channelId, webhookId)}/deliveries`, { limit: 20, cursor })),
+                    replay: (channelId, webhookId, deliveryId) => request("workspace.channels.webhooks.replay", `${webhook(channelId, webhookId)}/deliveries/${segment(deliveryId)}/replay`, { method: "POST" }),
+                    test: (channelId, webhookId) => request("workspace.channels.webhooks.test", `${webhook(channelId, webhookId)}/test`, { method: "POST" }),
+                },
+            } };
+    }
+    return { platform, workspace };
+}

package/dist/next.d.ts

@@ -0,0 +1,2 @@
+import "server-only";
+export * from "./index.js";

package/dist/next.js

@@ -0,0 +1,2 @@
+import "server-only";
+export * from "./index.js";

package/dist/types.d.ts

@@ -0,0 +1,125 @@
+export type ChannelStatus = "active" | "disabled";
+export type ChannelWebhookStatus = "active" | "disabled";
+export type ChannelWebhookHealth = "healthy" | "degraded" | "dead" | "idle" | "disabled";
+export interface ChannelToken {
+    id: string;
+    name: string;
+    token_hint: string;
+    is_active: boolean;
+    created_at: string;
+    last_used_at?: string;
+    revoked_at?: string;
+}
+export interface WorkspaceChannel {
+    id: string;
+    kind: string;
+    name: string;
+    site_url: string;
+    status: string;
+    tokens: ChannelToken[];
+    created_at: string;
+}
+export interface PlatformChannel {
+    id: string;
+    kind: string;
+    name: string;
+    saas_app: string;
+    workspace_id: string;
+    workspace_name: string;
+    workspace_slug: string;
+    status: string;
+    active_tokens: number;
+    revoked_tokens: number;
+    last_used_at?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface ChannelMint<TChannel> {
+    channel: TChannel;
+    token_id: string;
+    raw_token: string;
+}
+export interface ChannelAudit {
+    id: string;
+    channel_id: string;
+    token_id?: string;
+    webhook_id?: string;
+    saas_app: string;
+    workspace_id: string;
+    operator_id: string;
+    authority_level: string;
+    action: string;
+    outcome: string;
+    reason: string;
+    request_id?: string;
+    before_state?: unknown;
+    after_state?: unknown;
+    created_at: string;
+}
+export interface ChannelWebhook {
+    id: string;
+    channel_id: string;
+    channel_name?: string;
+    saas_app?: string;
+    workspace_id?: string;
+    workspace_name?: string;
+    workspace_slug?: string;
+    url: string;
+    event_types: string[];
+    status: ChannelWebhookStatus;
+    health?: ChannelWebhookHealth;
+    pending_count: number;
+    dead_count: number;
+    last_error?: string;
+    last_delivered_at?: string;
+    last_failed_at?: string;
+    oldest_pending_at?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface ChannelWebhookDelivery {
+    id: string;
+    webhook_id?: string;
+    event_id: string;
+    event_type: string;
+    status: string;
+    attempt_count: number;
+    next_attempt_at: string;
+    last_error?: string;
+    delivered_at?: string;
+    dead_at?: string;
+    created_at: string;
+}
+export interface CursorPage<T> {
+    items: T[];
+    next_cursor?: string;
+    has_more: boolean;
+}
+export interface WebhookPage extends CursorPage<ChannelWebhook> {
+    event_types: string[];
+}
+export interface WebhookSecret {
+    webhook: ChannelWebhook;
+    secret: string;
+}
+export interface PlatformChannelDetail {
+    channel: PlatformChannel;
+    tokens: ChannelToken[];
+    audit: ChannelAudit[];
+}
+export interface ChannelFilters {
+    q?: string;
+    saas_app?: string;
+    status?: string;
+    token_state?: string;
+    usage?: string;
+    health?: string;
+    cursor?: string;
+}
+export interface WebhookWrite {
+    url?: string;
+    event_types?: string[];
+    status?: ChannelWebhookStatus;
+    reason?: string;
+    confirm?: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@c1m-public/control-client",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Typed server-side client for C1M platform and workspace control APIs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cloud1mediaLtd/mml-js.git",
+    "directory": "packages/control-client"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./next": { "types": "./dist/next.d.ts", "default": "./dist/next.js" }
+  },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "pnpm clean && tsc -p tsconfig.build.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "type-check": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": { "server-only": "0.0.1" },
+  "devDependencies": { "typescript": "5.9.3", "vitest": "^4.1.4" }
+}