@onpeek/nuvio 1.0.0

package/dist/nuvio/ops/sessions.js

@@ -0,0 +1,36 @@
+import { NuvioError } from '../errors.js';
+export async function listSessions(client) {
+    return client.rpc('list_my_sessions', {});
+}
+export async function revokeSession(client, sessionId, apply) {
+    const sessions = await listSessions(client);
+    const target = sessions.find((s) => s.session_id === sessionId);
+    if (!target)
+        throw new NuvioError(`Session ${sessionId} not found`);
+    const diff = [`- session ${sessionId} (${target.device_name ?? target.client_name ?? 'unknown device'})`];
+    if (target.is_current) {
+        diff.push('! this is the current session; revoking it will require a new sign-in');
+    }
+    if (apply) {
+        await client.rpc('revoke_my_session', { p_session_id: sessionId });
+    }
+    return { applied: apply, changed: true, before: target, after: target, diff };
+}
+export async function registerDevice(client, device, apply) {
+    if (apply) {
+        await client.rpc('register_current_device', {
+            p_installation_id: device.installation_id,
+            p_client_name: device.client_name,
+            p_client_version: device.client_version ?? '',
+            p_device_name: device.device_name ?? '',
+            p_platform: device.platform ?? '',
+        });
+    }
+    return {
+        applied: apply,
+        changed: true,
+        before: {},
+        after: device,
+        diff: [`~ register device ${device.device_name ?? device.client_name}`],
+    };
+}

package/dist/nuvio/ops/settings.js

@@ -0,0 +1,143 @@
+import { setPath, unsetPath } from '../paths.js';
+const UNSAFE_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+function assertSafeKey(key) {
+    if (UNSAFE_KEYS.has(key))
+        throw new Error(`Unsafe path segment: ${key}`);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function clone(value) {
+    return structuredClone(value);
+}
+/**
+ * Deep-merge a patch into a base value.
+ * - object + object -> recursive merge
+ * - array -> replace the whole array
+ * - scalar / type mismatch -> replace the subtree
+ * - null is a normal value (it replaces)
+ * Deletion only happens through `unset`, never by merging.
+ */
+export function deepMerge(base, patch) {
+    if (isPlainObject(base) && isPlainObject(patch)) {
+        const out = clone(base);
+        for (const [key, value] of Object.entries(patch)) {
+            assertSafeKey(key);
+            out[key] = Object.prototype.hasOwnProperty.call(base, key) ? deepMerge(base[key], value) : clone(value);
+        }
+        return out;
+    }
+    return clone(patch);
+}
+function truncate(value, max = 160) {
+    if (value === undefined)
+        return 'undefined';
+    return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+function leaf(value) {
+    return value === undefined ? 'undefined' : truncate(JSON.stringify(value));
+}
+/** Precise leaf-level diff between two settings trees (arrays are treated as leaves). */
+export function diffTree(before, after, path = '', out = []) {
+    if (JSON.stringify(before) === JSON.stringify(after))
+        return out;
+    if (isPlainObject(before) && isPlainObject(after)) {
+        const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+        for (const key of [...keys].sort()) {
+            diffTree(before[key], after[key], path ? `${path}.${key}` : key, out);
+        }
+        return out;
+    }
+    out.push(`~ ${path || '(root)'}: ${leaf(before)} -> ${leaf(after)}`);
+    return out;
+}
+/** Apply patch -> set -> unset (in that order) to a settings tree. Pure. */
+export function applySettingsEdit(base, edit) {
+    let after = clone(base ?? {});
+    if (edit.patch)
+        after = deepMerge(after, edit.patch);
+    for (const { path, value } of edit.set ?? [])
+        after = setPath(after, path, value);
+    for (const path of edit.unset ?? [])
+        after = unsetPath(after, path);
+    return { before: base ?? {}, after, diff: diffTree(base ?? {}, after) };
+}
+export function assertEditProvided(edit) {
+    if (!edit.patch && !edit.set?.length && !edit.unset?.length) {
+        throw new Error('Provide at least one of: patch, set, unset.');
+    }
+}
+export async function getSettings(client, profileId, platform) {
+    const rows = await client.readRpc('sync_pull_profile_settings_blob', {
+        p_profile_id: profileId,
+        p_platform: platform,
+    });
+    return rows[0] ?? null;
+}
+/** True when an error is an optimistic-concurrency rejection (guarded write). */
+export function isConcurrencyConflict(error) {
+    const e = error;
+    if (e?.code === '40001' || e?.status === 409)
+        return true;
+    return typeof e?.message === 'string' && /changed on another device|concurrency|conflict/i.test(e.message);
+}
+export async function writeSettings(client, profileId, platform, json, updatedAt, originId) {
+    try {
+        const result = await client.rpc('sync_push_profile_settings_blob_guarded', {
+            p_profile_id: profileId,
+            p_platform: platform,
+            p_settings_json: json,
+            p_expected_updated_at: updatedAt,
+        });
+        return { revision: typeof result === 'string' && result ? result : null, guarded: true };
+    }
+    catch (error) {
+        if (isMissingFunction(error)) {
+            await client.rpc('sync_push_profile_settings_blob', {
+                p_profile_id: profileId,
+                p_platform: platform,
+                p_settings_json: json,
+                p_origin_client_id: originId,
+            });
+            return { revision: null, guarded: false };
+        }
+        throw error;
+    }
+}
+export async function updateSettings(client, profileId, platform, edit, originId, apply) {
+    assertEditProvided(edit);
+    const current = await getSettings(client, profileId, platform);
+    const { before, after, diff } = applySettingsEdit(current?.settings_json ?? {}, edit);
+    if (apply && diff.length > 0) {
+        await writeSettings(client, profileId, platform, after, current?.updated_at ?? null, originId);
+    }
+    return { applied: apply && diff.length > 0, changed: diff.length > 0, before, after, diff };
+}
+export async function getHomeCatalogSettings(client, profileId, platform) {
+    const rows = await client.readRpc('sync_pull_home_catalog_settings', {
+        p_profile_id: profileId,
+        p_platform: platform,
+    });
+    return rows[0] ?? null;
+}
+async function writeHomeCatalog(client, profileId, platform, json, originId) {
+    await client.rpc('sync_push_home_catalog_settings', {
+        p_profile_id: profileId,
+        p_platform: platform,
+        p_settings_json: json,
+        p_origin_client_id: originId,
+    });
+}
+export async function updateHomeCatalogSettings(client, profileId, platform, edit, originId, apply) {
+    assertEditProvided(edit);
+    const current = await getHomeCatalogSettings(client, profileId, platform);
+    const { before, after, diff } = applySettingsEdit(current?.settings_json ?? {}, edit);
+    if (apply && diff.length > 0) {
+        await writeHomeCatalog(client, profileId, platform, after, originId);
+    }
+    return { applied: apply && diff.length > 0, changed: diff.length > 0, before, after, diff };
+}
+function isMissingFunction(error) {
+    const e = error;
+    return e?.code === 'PGRST202' || e?.status === 404;
+}

package/dist/nuvio/ops/trackers.js

@@ -0,0 +1,80 @@
+import { NuvioError } from '../errors.js';
+export const TRACKERS = ['mal', 'anilist', 'kitsu'];
+function assertTracker(tracker) {
+    const key = tracker.trim().toLowerCase();
+    if (!TRACKERS.includes(key)) {
+        throw new NuvioError(`Unsupported tracker "${tracker}". Supported: ${TRACKERS.join(', ')}`);
+    }
+    return key;
+}
+export async function listTrackerTokens(client, profileId) {
+    return client.readRpc('get_tracker_tokens', { p_profile_id: profileId });
+}
+export async function listTrackerSettings(client, profileId) {
+    return client.readRpc('get_profile_tracker_settings', { p_profile_id: profileId });
+}
+export async function setTrackerSettings(client, profileId, tracker, settings, apply) {
+    const key = assertTracker(tracker);
+    const before = await listTrackerSettings(client, profileId);
+    const existing = before.find((s) => s.tracker === key);
+    const merged = {
+        tracker: key,
+        enabled_statuses: settings.enabled_statuses ?? existing?.enabled_statuses ?? [],
+        row_order: settings.row_order ?? existing?.row_order ?? [],
+        send_progress: settings.send_progress ?? existing?.send_progress ?? true,
+    };
+    const after = existing ? before.map((s) => (s.tracker === key ? merged : s)) : [...before, merged];
+    const diff = [
+        `~ ${key} settings: enabled_statuses=${merged.enabled_statuses.length}, send_progress=${merged.send_progress}`,
+    ];
+    if (apply) {
+        await client.rpc('upsert_profile_tracker_settings', {
+            p_profile_id: profileId,
+            p_tracker: key,
+            p_enabled_statuses: merged.enabled_statuses,
+            p_row_order: merged.row_order,
+            p_send_progress: merged.send_progress,
+        });
+    }
+    return { applied: apply, changed: true, before, after, diff };
+}
+export async function setTrackerToken(client, profileId, tracker, token, apply) {
+    const key = assertTracker(tracker);
+    if (!token.access_token)
+        throw new NuvioError('access_token is required to link a tracker');
+    const before = await listTrackerTokens(client, profileId);
+    const after = [
+        ...before.filter((t) => t.tracker !== key),
+        {
+            tracker: key,
+            access_token: token.access_token,
+            refresh_token: token.refresh_token,
+            tracker_user_id: token.tracker_user_id,
+            tracker_username: token.username,
+        },
+    ];
+    if (apply) {
+        await client.rpc('upsert_tracker_tokens', {
+            p_profile_id: profileId,
+            p_tracker: key,
+            p_access_token: token.access_token,
+            p_refresh_token: token.refresh_token ?? '',
+            p_expires_in_seconds: token.expires_in_seconds ?? 3600,
+            p_tracker_user_id: token.tracker_user_id ?? '',
+            p_username: token.username ?? '',
+        });
+    }
+    return { applied: apply, changed: true, before, after, diff: [`~ link ${key} tracker`] };
+}
+export async function unlinkTracker(client, profileId, tracker, apply) {
+    const key = assertTracker(tracker);
+    const before = await listTrackerTokens(client, profileId);
+    if (!before.some((t) => t.tracker === key)) {
+        throw new NuvioError(`Tracker "${key}" is not linked on profile ${profileId}`);
+    }
+    const after = before.filter((t) => t.tracker !== key);
+    if (apply) {
+        await client.rpc('clear_tracker_tokens', { p_profile_id: profileId, p_tracker: key });
+    }
+    return { applied: apply, changed: true, before, after, diff: [`- unlink ${key} tracker`] };
+}

package/dist/nuvio/ops/transitions.js

@@ -0,0 +1,100 @@
+import { historyKeyOf, libraryKeyOf, progressKeyOf, storedProgressKey } from '../keys.js';
+/**
+ * Pure state transitions shared by the direct ops and the plan planners. Both
+ * paths MUST produce the same `after` state and diff for the same inputs.
+ * Timestamps are injected so several operations in one plan are deterministic.
+ */
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = canonical(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+function same(a, b) {
+    return JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+}
+export function planLibraryAdd(before, items, now) {
+    const after = structuredClone(before);
+    const diff = [];
+    for (const item of items) {
+        const key = libraryKeyOf(item);
+        const index = after.findIndex((i) => libraryKeyOf(i) === key);
+        const previous = index >= 0 ? after[index] : undefined;
+        const merged = { ...previous, ...item, added_at: item.added_at ?? previous?.added_at ?? now };
+        if (previous && same(previous, merged))
+            continue;
+        diff.push(previous ? `~ update library item ${key}` : `+ library ${key}`);
+        if (index >= 0)
+            after[index] = merged;
+        else
+            after.push(merged);
+    }
+    return { after, diff };
+}
+export function planLibraryRemove(before, keys) {
+    const wanted = new Set(keys.map((k) => libraryKeyOf(k)));
+    return {
+        after: before.filter((i) => !wanted.has(libraryKeyOf(i))),
+        diff: keys.map((k) => `- library ${libraryKeyOf(k)}`),
+    };
+}
+export function planProgressSet(before, entries, now) {
+    const after = structuredClone(before);
+    const diff = [];
+    for (const entry of entries) {
+        const key = progressKeyOf(entry);
+        const index = after.findIndex((p) => storedProgressKey(p) === key);
+        const previous = index >= 0 ? after[index] : undefined;
+        const merged = { ...previous, ...entry, last_watched: entry.last_watched ?? now };
+        const scope = entry.season != null ? ` S${entry.season}E${entry.episode}` : '';
+        if (previous && same(previous, merged))
+            continue;
+        diff.push(`~ progress ${entry.content_type}:${entry.content_id}${scope} @ ${entry.position}/${entry.duration}`);
+        if (index >= 0)
+            after[index] = merged;
+        else
+            after.push(merged);
+    }
+    return { after, diff };
+}
+export function planProgressDelete(before, keys) {
+    const wanted = new Set(keys.map((k) => progressKeyOf(k)));
+    return {
+        after: before.filter((p) => !wanted.has(progressKeyOf(p))),
+        diff: keys.map((k) => `- watch progress ${k.content_id}${k.season != null ? ` S${k.season}E${k.episode}` : ''}`),
+    };
+}
+export function planHistoryAdd(before, items, now) {
+    const after = structuredClone(before);
+    const diff = [];
+    for (const item of items) {
+        const key = historyKeyOf(item);
+        const index = after.findIndex((i) => historyKeyOf(i) === key);
+        const previous = index >= 0 ? after[index] : undefined;
+        const merged = { ...previous, ...item, watched_at: item.watched_at ?? previous?.watched_at ?? now };
+        if (previous && same(previous, merged))
+            continue;
+        const scope = item.season != null ? ` S${item.season}E${item.episode}` : '';
+        diff.push(previous
+            ? `~ watched ${item.content_type}:${item.content_id}${scope}`
+            : `+ watched ${item.content_type}:${item.content_id}${scope}`);
+        if (index >= 0)
+            after[index] = merged;
+        else
+            after.push(merged);
+    }
+    return { after, diff };
+}
+export function planHistoryDelete(before, keys) {
+    const wanted = new Set(keys.map((k) => historyKeyOf(k)));
+    return {
+        after: before.filter((i) => !wanted.has(historyKeyOf(i))),
+        diff: keys.map((k) => `- watch history ${k.content_id}${k.season != null ? ` S${k.season}E${k.episode}` : ''}`),
+    };
+}

package/dist/nuvio/paths.js

@@ -0,0 +1,74 @@
+const UNSAFE_SEGMENTS = new Set(['__proto__', 'prototype', 'constructor']);
+function assertSafeSegment(segment) {
+    if (UNSAFE_SEGMENTS.has(segment)) {
+        throw new Error(`Unsafe path segment: ${segment}`);
+    }
+}
+function isSafeSegment(segment) {
+    return !UNSAFE_SEGMENTS.has(segment);
+}
+export function setPath(root, path, value) {
+    const parts = path.split('.').filter(Boolean);
+    if (parts.length === 0)
+        throw new Error('Setting path cannot be empty');
+    const out = structuredClone(root);
+    let cursor = out;
+    for (let i = 0; i < parts.length - 1; i += 1) {
+        const key = parts[i];
+        assertSafeSegment(key);
+        const nextIsIndex = /^\d+$/.test(parts[i + 1]);
+        const container = cursor;
+        const existing = Array.isArray(cursor) ? cursor[Number(key)] : container[key];
+        if (existing === undefined || existing === null || typeof existing !== 'object') {
+            const created = nextIsIndex ? [] : {};
+            if (Array.isArray(cursor))
+                cursor[Number(key)] = created;
+            else
+                container[key] = created;
+            cursor = created;
+        }
+        else {
+            cursor = existing;
+        }
+    }
+    const last = parts[parts.length - 1];
+    assertSafeSegment(last);
+    if (Array.isArray(cursor) && /^\d+$/.test(last))
+        cursor[Number(last)] = value;
+    else
+        cursor[last] = value;
+    return out;
+}
+export function unsetPath(root, path) {
+    const parts = path.split('.').filter(Boolean);
+    if (parts.length === 0)
+        throw new Error('Setting path cannot be empty');
+    const out = structuredClone(root);
+    let cursor = out;
+    for (let i = 0; i < parts.length - 1; i += 1) {
+        const key = parts[i];
+        assertSafeSegment(key);
+        const existing = Array.isArray(cursor) ? cursor[Number(key)] : cursor[key];
+        if (existing === undefined || existing === null || typeof existing !== 'object')
+            return out;
+        cursor = existing;
+    }
+    const last = parts[parts.length - 1];
+    assertSafeSegment(last);
+    if (Array.isArray(cursor) && /^\d+$/.test(last))
+        cursor.splice(Number(last), 1);
+    else
+        delete cursor[last];
+    return out;
+}
+export function getPath(root, path) {
+    let cursor = root;
+    for (const key of path.split('.').filter(Boolean)) {
+        if (!isSafeSegment(key))
+            return undefined;
+        if (cursor === null || typeof cursor !== 'object')
+            return undefined;
+        cursor = Array.isArray(cursor) ? cursor[Number(key)] : cursor[key];
+    }
+    return cursor;
+}

package/dist/nuvio/safe-fetch.js

@@ -0,0 +1,131 @@
+import { isIP } from 'node:net';
+import { lookup } from 'node:dns/promises';
+import { NuvioError } from './errors.js';
+/**
+ * Fetches a JSON document from a user-supplied URL without allowing server-side
+ * request forgery: only http(s), no loopback/private/link-local/multicast targets,
+ * DNS re-resolution checked on every hop, redirects followed manually with the same
+ * checks, a hard timeout and a response-size cap.
+ */
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_BYTES = 1_000_000;
+const DEFAULT_MAX_REDIRECTS = 3;
+function isPrivateIPv4(ip) {
+    const parts = ip.split('.').map((p) => Number(p));
+    if (parts.length !== 4 || parts.some((p) => !Number.isInteger(p) || p < 0 || p > 255))
+        return true;
+    const [a, b] = parts;
+    if (a === 0 || a === 10 || a === 127)
+        return true;
+    if (a === 169 && b === 254)
+        return true; // link-local (cloud metadata)
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    if (a === 192 && b === 168)
+        return true;
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // CGNAT
+    if (a >= 224)
+        return true; // multicast / reserved
+    return false;
+}
+function isPrivateIPv6(ip) {
+    const lower = ip.toLowerCase();
+    if (lower === '::' || lower === '::1')
+        return true;
+    if (lower.startsWith('fc') || lower.startsWith('fd'))
+        return true; // fc00::/7 ULA
+    if (/^fe[89ab]/.test(lower))
+        return true; // fe80::/10 link-local
+    if (lower.startsWith('ff'))
+        return true; // multicast
+    const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (mapped)
+        return isPrivateIPv4(mapped[1]);
+    return false;
+}
+/** True when `ip` is not a globally routable unicast address. */
+export function isPrivateAddress(ip) {
+    const version = isIP(ip);
+    if (version === 4)
+        return isPrivateIPv4(ip);
+    if (version === 6)
+        return isPrivateIPv6(ip);
+    return true;
+}
+async function assertPublicHost(hostname) {
+    const literal = hostname.replace(/^\[|\]$/g, '');
+    if (isIP(literal)) {
+        if (isPrivateAddress(literal)) {
+            throw new NuvioError(`Refusing to fetch a private/loopback address: ${hostname}`);
+        }
+        return;
+    }
+    let addresses;
+    try {
+        addresses = await lookup(hostname, { all: true });
+    }
+    catch {
+        throw new NuvioError(`Could not resolve host: ${hostname}`);
+    }
+    if (addresses.length === 0)
+        throw new NuvioError(`Could not resolve host: ${hostname}`);
+    for (const { address } of addresses) {
+        if (isPrivateAddress(address)) {
+            throw new NuvioError(`Refusing to fetch a host that resolves to a private address: ${hostname}`);
+        }
+    }
+}
+async function readCapped(res, maxBytes) {
+    const declared = Number(res.headers.get('content-length') ?? '');
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        throw new NuvioError('Response body is too large');
+    }
+    const buffer = Buffer.from(await res.arrayBuffer());
+    if (buffer.byteLength > maxBytes)
+        throw new NuvioError('Response body is too large');
+    return buffer.toString('utf8');
+}
+export async function fetchJsonFromPublicUrl(rawUrl, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+    let current = rawUrl;
+    for (let hop = 0; hop <= maxRedirects; hop += 1) {
+        let url;
+        try {
+            url = new URL(current);
+        }
+        catch {
+            throw new NuvioError(`Invalid URL: ${current}`);
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            throw new NuvioError('Only http(s) URLs are supported');
+        }
+        await assertPublicHost(url.hostname);
+        const res = await fetch(url, {
+            redirect: 'manual',
+            headers: { accept: 'application/json' },
+            signal: AbortSignal.timeout(timeoutMs),
+        }).catch((error) => {
+            throw new NuvioError(`Fetch failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        if (res.status >= 300 && res.status < 400) {
+            const location = res.headers.get('location');
+            if (!location)
+                throw new NuvioError(`Redirect without a Location header [http ${res.status}]`);
+            current = new URL(location, url).toString();
+            continue;
+        }
+        if (!res.ok)
+            throw new NuvioError(`Fetch failed [http ${res.status}]`);
+        const text = await readCapped(res, maxBytes);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new NuvioError('Response was not valid JSON');
+        }
+    }
+    throw new NuvioError('Too many redirects');
+}