@taskup/web 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TaskUp contributors
+
+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,35 @@
+# @taskup/web
+
+Small browser SDK for registered TaskUp controls and opt-in error reporting. It never reads cookies, form values, request bodies, tokens, or environment variables.
+
+## Install
+
+After the first public npm release:
+
+    npm install @taskup/web
+
+Until then, install the package file provided on the TaskUp setup page. A local package can be made with:
+
+    npm pack ./packages/web
+
+## Next.js
+
+Copy this into a client component and replace the example keys with controls you registered in TaskUp:
+
+    "use client";
+    import { useTaskUp } from "@taskup/web/react";
+
+    export function TaskUpExample() {
+      const taskup = useTaskUp({
+        projectKey: "YOUR_PUBLIC_PROJECT_KEY",
+        endpoint: "https://task-up.org",
+      });
+      return <>
+        <h1>{taskup.string("homepage_headline", "Welcome")}</h1>
+        <button disabled={!taskup.boolean("registrations_open", true)}>Register</button>
+      </>;
+    }
+
+The hook refreshes controls and reports uncaught browser errors. The fallback stays in use when TaskUp is unavailable. For non-React apps, import createTaskUp from @taskup/web, call refresh(), and read controls with string(), number(), or boolean().
+
+For handled errors, call reportError(error) or reportNetworkFailure(path, status). Supply a userId callback only if your app has already authenticated the user. A deployment version can be supplied in the options.

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export type TaskUpOptions = {
+    projectKey: string;
+    endpoint: string;
+    userId?: () => string | undefined;
+    version?: string;
+};
+type Value = string | number | boolean;
+/** A small, opt-in browser client. It never reads cookies, forms, bodies or tokens. */
+export declare function createTaskUp(options: TaskUpOptions): {
+    refresh: () => Promise<void>;
+    subscribe(listener: () => void): () => boolean;
+    getSnapshot: () => number;
+    string: (key: string, fallback: string) => string;
+    number: (key: string, fallback: number) => number;
+    boolean: (key: string, fallback: boolean) => boolean;
+    get: <T extends Value>(key: string, fallback: T) => T;
+    reportError(error: unknown): void;
+    reportNetworkFailure(path: string, status: number): void;
+    observeGlobalErrors(): () => void;
+};
+export {};

package/dist/index.js

@@ -0,0 +1,64 @@
+/** A small, opt-in browser client. It never reads cookies, forms, bodies or tokens. */
+export function createTaskUp(options) {
+    const base = options.endpoint.replace(/\/$/, "");
+    const values = new Map();
+    const listeners = new Set();
+    let connected = false;
+    let revision = 0;
+    const notify = () => { revision++; listeners.forEach(listener => listener()); };
+    const post = (path, payload) => {
+        if (typeof window === "undefined")
+            return Promise.resolve(undefined);
+        return fetch(`${base}${path}`, { method: "POST", mode: "cors", credentials: "omit", headers: { "Content-Type": "text/plain" }, body: JSON.stringify(payload), keepalive: true }).catch(() => undefined);
+    };
+    async function refresh() {
+        if (typeof window === "undefined")
+            return;
+        try {
+            const response = await fetch(`${base}/api/v1/controls?projectKey=${encodeURIComponent(options.projectKey)}`, { mode: "cors", credentials: "omit" });
+            if (!response.ok)
+                return;
+            const result = await response.json();
+            for (const [key, value] of Object.entries(result.values ?? {}))
+                if (["string", "number", "boolean"].includes(typeof value))
+                    values.set(key, value);
+            notify();
+            if (!connected) {
+                const signal = await post("/api/v1/hello", { projectKey: options.projectKey });
+                connected = signal?.ok === true;
+            }
+        }
+        catch { /* Fallbacks remain active while TaskUp is unavailable. */ }
+    }
+    function read(key, fallback) { const value = values.get(key); return typeof value === typeof fallback ? value : fallback; }
+    function report(kind, message) {
+        if (typeof window === "undefined")
+            return;
+        void post("/api/v1/events", {
+            projectKey: options.projectKey, kind,
+            message: String(message).replace(/[?#][^\s]+/g, "").slice(0, 2000),
+            route: window.location.pathname,
+            userId: options.userId?.(), version: options.version,
+        });
+    }
+    return {
+        refresh,
+        subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+        getSnapshot: () => revision,
+        string: (key, fallback) => read(key, fallback),
+        number: (key, fallback) => read(key, fallback),
+        boolean: (key, fallback) => read(key, fallback),
+        get: read,
+        reportError(error) { report("runtime", error instanceof Error ? error.message : String(error)); },
+        reportNetworkFailure(path, status) { report("network", `Request failed: ${path.split("?")[0]} (HTTP ${status})`); },
+        observeGlobalErrors() {
+            if (typeof window === "undefined")
+                return () => { };
+            const onError = (event) => report("runtime", event.message || "Unhandled error");
+            const onRejection = (event) => report("runtime", event.reason instanceof Error ? event.reason.message : "Unhandled promise rejection");
+            window.addEventListener("error", onError);
+            window.addEventListener("unhandledrejection", onRejection);
+            return () => { window.removeEventListener("error", onError); window.removeEventListener("unhandledrejection", onRejection); };
+        },
+    };
+}

package/dist/react.d.ts

@@ -0,0 +1,14 @@
+import { type TaskUpOptions } from "./index";
+/** Reads registered controls and refreshes the component after TaskUp updates them. */
+export declare function useTaskUp(options: TaskUpOptions): {
+    refresh: () => Promise<void>;
+    subscribe(listener: () => void): () => boolean;
+    getSnapshot: () => number;
+    string: (key: string, fallback: string) => string;
+    number: (key: string, fallback: number) => number;
+    boolean: (key: string, fallback: boolean) => boolean;
+    get: <T extends string | number | boolean>(key: string, fallback: T) => T;
+    reportError(error: unknown): void;
+    reportNetworkFailure(path: string, status: number): void;
+    observeGlobalErrors(): () => void;
+};

package/dist/react.js

@@ -0,0 +1,14 @@
+"use client";
+import { useEffect, useMemo, useSyncExternalStore } from "react";
+import { createTaskUp } from "./index";
+/** Reads registered controls and refreshes the component after TaskUp updates them. */
+export function useTaskUp(options) {
+    const { projectKey, endpoint, userId, version } = options;
+    const client = useMemo(() => createTaskUp({ projectKey, endpoint, userId, version }), [projectKey, endpoint, userId, version]);
+    useSyncExternalStore(client.subscribe, client.getSnapshot, () => 0);
+    useEffect(() => {
+        void client.refresh();
+        return client.observeGlobalErrors();
+    }, [client]);
+    return client;
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@taskup/web",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Small browser SDK for TaskUp controls and error reporting",
+  "homepage": "https://task-up.org",
+  "license": "MIT",
+  "publishConfig": { "access": "public" },
+  "files": ["dist", "README.md", "LICENSE"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "peerDependencies": { "react": ">=18" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "devDependencies": { "@types/react": "^19.0.0", "react": "^19.0.0", "typescript": "^5.0.0" }
+}