@guinetik/primitives-ts 0.14.0 → 0.15.0

package/dist/home-dashboard.types.d.ts

@@ -1,5 +1,5 @@
-import type { GeoLocation } from './geo.types';
-export type HomeWidgetType = "launchpad" | "clock" | "webpage" | "analytics" | "utility" | "news" | "weather" | "currency";
+import type { GeoLocation } from "./geo.types";
+export type HomeWidgetType = "launchpad" | "clock" | "webpage" | "analytics" | "utility" | "news" | "weather" | "currency" | "crypto" | "apod";
 export type HomeWidgetColSpan = 1 | 2 | 3;
 export interface LaunchpadWidgetConfig {
     /** Launchpad group ids to show. Omitted on legacy widgets means all groups. */
@@ -51,7 +51,20 @@ export interface CurrencyWidgetConfig {
     quote: string;
     defaultAmount: number;
 }
-export type HomeWidgetConfig = LaunchpadWidgetConfig | ClockWidgetConfig | WebpageWidgetConfig | AnalyticsWidgetConfig | UtilityWidgetConfig | NewsWidgetConfig | WeatherWidgetConfig | CurrencyWidgetConfig;
+export declare const CRYPTO_MAX_COINS = 5;
+export interface CryptoWidgetConfig {
+    /** Enabled provider to use. Omitted means the category default. */
+    providerId?: string;
+    /** CoinGecko-style coin ids, e.g. "bitcoin". */
+    coins: string[];
+    /** Uppercase ISO 4217 code the coins are priced in, e.g. "BRL". */
+    vsCurrency: string;
+}
+export interface ApodWidgetConfig {
+    /** Enabled NASA provider to use. Omitted means the NASA category default. */
+    providerId?: string;
+}
+export type HomeWidgetConfig = LaunchpadWidgetConfig | ClockWidgetConfig | WebpageWidgetConfig | AnalyticsWidgetConfig | UtilityWidgetConfig | NewsWidgetConfig | WeatherWidgetConfig | CurrencyWidgetConfig | CryptoWidgetConfig | ApodWidgetConfig;
 export interface HomeDashboardWidget {
     id: string;
     /** Optional user-defined chrome title. The widget type is used when omitted. */
@@ -71,4 +84,6 @@ export declare const CLOCK_DEFAULT_TIMEZONE = "America/Sao_Paulo";
 export declare const CLOCK_DEFAULT_PRESET = "aurora";
 export declare const CLOCK_PRESETS: readonly ["aurora", "grid", "binary", "day-night", "location-photos"];
 export declare function isHomeWidgetType(value: string): value is HomeWidgetType;
+export type HomeWidgetConfigValidationResult = string | null;
+export declare function validateHomeWidgetConfig(type: HomeWidgetType, config: unknown): HomeWidgetConfigValidationResult;
 //# sourceMappingURL=home-dashboard.types.d.ts.map

package/dist/home-dashboard.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"home-dashboard.types.d.ts","sourceRoot":"","sources":["../src/home-dashboard.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,MAAM,cAAc,GACtB,WAAW,GACX,OAAO,GACP,SAAS,GACT,WAAW,GACX,SAAS,GACT,MAAM,GACN,SAAS,GACT,UAAU,CAAC;AAEf,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAE1C,MAAM,WAAW,qBAAqB;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,gBAAgB,kEAInB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,CAAC,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,gBAAgB,GACxB,qBAAqB,GACrB,iBAAiB,GACjB,mBAAmB,GACnB,qBAAqB,GACrB,mBAAmB,GACnB,gBAAgB,GAChB,mBAAmB,GACnB,oBAAoB,CAAC;AAEzB,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,mBAAmB,EAAE,CAAC;CAChC;AAED,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAStD,CAAC;AAEF,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAE1D,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAE7C,eAAO,MAAM,aAAa,uEAMhB,CAAC;AAEX,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,cAAc,CAEvE"}
+{"version":3,"file":"home-dashboard.types.d.ts","sourceRoot":"","sources":["../src/home-dashboard.types.ts"],"names":[],"mappings":"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"}

package/dist/home-dashboard.types.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLOCK_PRESETS = exports.CLOCK_DEFAULT_PRESET = exports.CLOCK_DEFAULT_TIMEZONE = exports.MAX_HOME_WIDGETS = exports.HOME_WIDGET_TYPES = exports.UTILITY_TOOL_IDS = void 0;
+exports.CLOCK_PRESETS = exports.CLOCK_DEFAULT_PRESET = exports.CLOCK_DEFAULT_TIMEZONE = exports.MAX_HOME_WIDGETS = exports.HOME_WIDGET_TYPES = exports.CRYPTO_MAX_COINS = exports.UTILITY_TOOL_IDS = void 0;
 exports.isHomeWidgetType = isHomeWidgetType;
+exports.validateHomeWidgetConfig = validateHomeWidgetConfig;
 exports.UTILITY_TOOL_IDS = [
     "unit-converter",
     "text-workbench",
     "date-calculator",
 ];
+exports.CRYPTO_MAX_COINS = 5;
 exports.HOME_WIDGET_TYPES = [
     "launchpad",
     "clock",
@@ -16,6 +18,8 @@ exports.HOME_WIDGET_TYPES = [
     "news",
     "weather",
     "currency",
+    "crypto",
+    "apod",
 ];
 exports.MAX_HOME_WIDGETS = 30;
 exports.CLOCK_DEFAULT_TIMEZONE = "America/Sao_Paulo";
@@ -30,3 +34,193 @@ exports.CLOCK_PRESETS = [
 function isHomeWidgetType(value) {
     return exports.HOME_WIDGET_TYPES.includes(value);
 }
+function configRecord(config) {
+    return typeof config === "object" && config !== null && !Array.isArray(config)
+        ? config
+        : null;
+}
+function providerIdError(config) {
+    const providerId = config.providerId;
+    return providerId !== undefined &&
+        (typeof providerId !== "string" ||
+            providerId.trim().length === 0 ||
+            providerId.length > 200)
+        ? "widget providerId must be a non-empty string"
+        : null;
+}
+const HOME_WIDGET_CONFIG_VALIDATORS = {
+    launchpad(config) {
+        const value = configRecord(config);
+        if (!value)
+            return "launchpad widget config must be an object";
+        const ids = value.groupIds;
+        if (ids !== undefined &&
+            (!Array.isArray(ids) ||
+                ids.length === 0 ||
+                ids.some((id) => typeof id !== "string" || id.trim().length === 0) ||
+                new Set(ids).size !== ids.length)) {
+            return "launchpad widget config groupIds must be a non-empty array of unique strings";
+        }
+        return null;
+    },
+    clock(config) {
+        const value = configRecord(config);
+        if (!value ||
+            typeof value.timeZone !== "string" ||
+            value.timeZone.length === 0 ||
+            typeof value.preset !== "string" ||
+            value.preset.length === 0) {
+            return "clock widget config requires timeZone and preset";
+        }
+        return value.hour12 !== undefined && typeof value.hour12 !== "boolean"
+            ? "clock widget hour12 must be a boolean"
+            : null;
+    },
+    webpage(config) {
+        const value = configRecord(config);
+        if (!value || typeof value.url !== "string") {
+            return "webpage widget config url must be a string";
+        }
+        return value.url.length > 0 && !/^https?:\/\//i.test(value.url)
+            ? "webpage widget config url must start with http:// or https://"
+            : null;
+    },
+    analytics(config) {
+        const propertyId = configRecord(config)?.propertyId;
+        return typeof propertyId !== "string" ||
+            !/^properties\/\d+$/.test(propertyId)
+            ? "analytics widget config propertyId must look like properties/123456"
+            : null;
+    },
+    utility(config) {
+        const value = configRecord(config);
+        if (!value)
+            return "utility widget config must be an object";
+        if (value.schemaVersion !== 1)
+            return "utility widget config schemaVersion must be 1";
+        if (typeof value.toolId !== "string" ||
+            !exports.UTILITY_TOOL_IDS.includes(value.toolId)) {
+            return "utility widget config contains an unsupported toolId";
+        }
+        const settings = configRecord(value.settings);
+        if (!settings)
+            return "utility widget settings must be an object";
+        return new TextEncoder().encode(JSON.stringify(settings)).length > 4096
+            ? "utility widget settings are too large"
+            : null;
+    },
+    news(config) {
+        const value = configRecord(config);
+        if (!value)
+            return "news widget config must be an object";
+        const providerError = providerIdError(value);
+        if (providerError)
+            return providerError;
+        if (typeof value.limit !== "number" ||
+            !Number.isInteger(value.limit) ||
+            value.limit < 1 ||
+            value.limit > 12) {
+            return "news widget limit must be an integer from 1 to 12";
+        }
+        const refresh = value.refreshMinutes;
+        return refresh !== undefined &&
+            (typeof refresh !== "number" ||
+                !Number.isInteger(refresh) ||
+                refresh < 1 ||
+                refresh > 1440)
+            ? "news widget refreshMinutes must be an integer from 1 to 1440"
+            : null;
+    },
+    weather(config) {
+        const value = configRecord(config);
+        if (!value)
+            return "weather widget requires a valid location";
+        const providerError = providerIdError(value);
+        if (providerError)
+            return providerError;
+        const location = value.location;
+        const legacy = typeof location === "string" &&
+            location.trim().length >= 2 &&
+            location.length <= 120;
+        const resolved = configRecord(location);
+        const valid = resolved !== null &&
+            typeof resolved.name === "string" &&
+            resolved.name.trim().length > 0 &&
+            resolved.name.length <= 120 &&
+            typeof resolved.lat === "number" &&
+            Number.isFinite(resolved.lat) &&
+            resolved.lat >= -90 &&
+            resolved.lat <= 90 &&
+            typeof resolved.lon === "number" &&
+            Number.isFinite(resolved.lon) &&
+            resolved.lon >= -180 &&
+            resolved.lon <= 180 &&
+            typeof resolved.timeZone === "string" &&
+            resolved.timeZone.trim().length > 0 &&
+            resolved.timeZone.length <= 120;
+        return legacy || valid ? null : "weather widget requires a valid location";
+    },
+    currency(config) {
+        const value = configRecord(config);
+        if (!value)
+            return "currency widget config is invalid";
+        const providerError = providerIdError(value);
+        if (providerError)
+            return providerError;
+        if ("currencies" in value || "home" in value) {
+            const currencies = value.currencies;
+            return typeof value.home !== "string" ||
+                !/^[A-Z]{3}$/.test(value.home) ||
+                !Array.isArray(currencies) ||
+                currencies.length < 1 ||
+                currencies.length > 3 ||
+                currencies.some((code) => typeof code !== "string" || !/^[A-Z]{3}$/.test(code)) ||
+                new Set(currencies).size !== currencies.length
+                ? "currency widget requires a home currency and 1 to 3 unique currencies"
+                : null;
+        }
+        return typeof value.base !== "string" ||
+            typeof value.quote !== "string" ||
+            !/^[A-Z]{3}$/.test(value.base) ||
+            !/^[A-Z]{3}$/.test(value.quote) ||
+            typeof value.defaultAmount !== "number" ||
+            !Number.isFinite(value.defaultAmount) ||
+            value.defaultAmount < 0
+            ? "currency widget requires base, quote, and defaultAmount"
+            : null;
+    },
+    crypto(config) {
+        const value = configRecord(config);
+        if (!value)
+            return "crypto widget config must be an object";
+        const providerError = providerIdError(value);
+        if (providerError)
+            return providerError;
+        const coins = value.coins;
+        if (!Array.isArray(coins) ||
+            coins.length < 1 ||
+            coins.length > exports.CRYPTO_MAX_COINS ||
+            coins.some((coin) => typeof coin !== "string" || !/^[a-z0-9-]{1,100}$/.test(coin)) ||
+            new Set(coins).size !== coins.length) {
+            return `crypto widget requires 1 to ${exports.CRYPTO_MAX_COINS} unique lowercase coin ids`;
+        }
+        return typeof value.vsCurrency !== "string" ||
+            !/^[A-Z]{3}$/.test(value.vsCurrency)
+            ? "crypto widget vsCurrency must be a 3-letter uppercase currency code"
+            : null;
+    },
+    apod(config) {
+        const value = configRecord(config);
+        if (!value)
+            return "apod widget config must be an object";
+        const providerError = providerIdError(value);
+        if (providerError)
+            return providerError;
+        return Object.keys(value).some((key) => key !== "providerId")
+            ? "apod widget config contains an unsupported setting"
+            : null;
+    },
+};
+function validateHomeWidgetConfig(type, config) {
+    return HOME_WIDGET_CONFIG_VALIDATORS[type](config);
+}

package/dist/home-dashboard.types.spec.js

@@ -16,13 +16,44 @@ describe("home dashboard types", () => {
             "news",
             "weather",
             "currency",
+            "crypto",
+            "apod",
         ]);
         expect((0, home_dashboard_types_1.isHomeWidgetType)("clock")).toBe(true);
         expect((0, home_dashboard_types_1.isHomeWidgetType)("analytics")).toBe(true);
         expect((0, home_dashboard_types_1.isHomeWidgetType)("utility")).toBe(true);
         expect((0, home_dashboard_types_1.isHomeWidgetType)("weather")).toBe(true);
+        expect((0, home_dashboard_types_1.isHomeWidgetType)("apod")).toBe(true);
         expect((0, home_dashboard_types_1.isHomeWidgetType)("stock-ticker")).toBe(false);
     });
+    it("validates the APOD provider selection", () => {
+        expect((0, home_dashboard_types_1.validateHomeWidgetConfig)("apod", {})).toBeNull();
+        expect((0, home_dashboard_types_1.validateHomeWidgetConfig)("apod", { providerId: "nasa-1" })).toBeNull();
+        expect((0, home_dashboard_types_1.validateHomeWidgetConfig)("apod", { providerId: "" })).not.toBeNull();
+    });
+    it("validates crypto widget configs", () => {
+        expect((0, home_dashboard_types_1.validateHomeWidgetConfig)("crypto", {
+            coins: ["bitcoin", "ethereum"],
+            vsCurrency: "BRL",
+        })).toBeNull();
+        expect((0, home_dashboard_types_1.validateHomeWidgetConfig)("crypto", {
+            providerId: "crypto-1",
+            coins: ["bitcoin"],
+            vsCurrency: "USD",
+        })).toBeNull();
+        const invalid = [
+            { coins: [], vsCurrency: "BRL" },
+            { coins: ["a", "b", "c", "d", "e", "f"], vsCurrency: "BRL" },
+            { coins: ["bitcoin", "bitcoin"], vsCurrency: "BRL" },
+            { coins: ["Bitcoin!"], vsCurrency: "BRL" },
+            { coins: ["bitcoin"], vsCurrency: "brl" },
+            { coins: ["bitcoin"], vsCurrency: "BRLX" },
+            { providerId: "", coins: ["bitcoin"], vsCurrency: "BRL" },
+        ];
+        for (const config of invalid) {
+            expect((0, home_dashboard_types_1.validateHomeWidgetConfig)("crypto", config)).not.toBeNull();
+        }
+    });
     it("stores a versioned allowlisted utility configuration", () => {
         const widget = {
             id: "utility-1",
@@ -133,3 +164,29 @@ describe("GeoLocation", () => {
         expect(weather.location).toBe("Cayenne");
     });
 });
+describe("home widget config validation", () => {
+    it("uses one shared validator for current and legacy currency configs", () => {
+        expect((0, home_dashboard_types_1.validateHomeWidgetConfig)("currency", {
+            home: "BRL",
+            currencies: ["USD", "EUR"],
+        })).toBeNull();
+        expect((0, home_dashboard_types_1.validateHomeWidgetConfig)("currency", {
+            base: "USD",
+            quote: "EUR",
+            defaultAmount: 1,
+        })).toBeNull();
+        expect((0, home_dashboard_types_1.validateHomeWidgetConfig)("currency", {
+            home: "BRL",
+            currencies: ["USD", "USD"],
+        })).toContain("unique currencies");
+    });
+    it("applies resolved-location constraints consistently", () => {
+        expect((0, home_dashboard_types_1.validateHomeWidgetConfig)("weather", {
+            location: { name: "Recife", lat: -8.05, lon: -34.9 },
+        })).toBe("weather widget requires a valid location");
+    });
+    it("keeps an empty webpage placeholder but rejects a missing URL", () => {
+        expect((0, home_dashboard_types_1.validateHomeWidgetConfig)("webpage", { url: "" })).toBeNull();
+        expect((0, home_dashboard_types_1.validateHomeWidgetConfig)("webpage", {})).toBe("webpage widget config url must be a string");
+    });
+});

package/dist/widget-services.types.d.ts

@@ -1,6 +1,132 @@
 /** Shared contracts for provider-backed dashboard widgets. */
-export type WidgetServiceKind = "news" | "weather" | "currency";
-export type WidgetServiceProviderType = "rss" | "open-meteo" | "frankfurter";
+export type WidgetServiceKind = "news" | "weather" | "currency" | "geo" | "crypto" | "nasa";
+export type WidgetServiceSettingValue = string | number | boolean;
+export type WidgetServiceSettings = Record<string, WidgetServiceSettingValue>;
+export interface WidgetServiceProviderSettingsMap {
+    rss: {
+        feedUrl: string;
+    };
+    "open-meteo": Record<string, never>;
+    frankfurter: Record<string, never>;
+    "google-places": {
+        apiKey: string;
+    };
+    coingecko: {
+        apiKey?: string;
+    };
+    nasa: {
+        apiKey?: string;
+    };
+}
+export type WidgetServiceProviderType = keyof WidgetServiceProviderSettingsMap;
+export interface WidgetServiceSettingsField {
+    key: string;
+    label: string;
+    input: "text" | "url" | "password";
+    required: boolean;
+    maxLength: number;
+    defaultValue?: string;
+}
+export interface WidgetServiceProviderDefinition<T extends WidgetServiceProviderType> {
+    type: T;
+    kind: WidgetServiceKind;
+    label: string;
+    settingsFields: readonly WidgetServiceSettingsField[];
+    secretSettingKeys: readonly (keyof WidgetServiceProviderSettingsMap[T] & string)[];
+    normalizeSettings(settings: WidgetServiceSettings): WidgetServiceProviderSettingsMap[T];
+}
+export declare const WIDGET_SERVICE_SECRET_MASK = "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022";
+declare function noSettings(): Record<string, never>;
+declare function normalizeRssSettings(settings: WidgetServiceSettings): {
+    feedUrl: string;
+};
+declare function normalizeGooglePlacesSettings(settings: WidgetServiceSettings): {
+    apiKey: string;
+};
+declare function normalizeCoingeckoSettings(settings: WidgetServiceSettings): {
+    apiKey?: string;
+};
+declare function normalizeOptionalApiKey(settings: WidgetServiceSettings): {
+    apiKey?: string;
+};
+/** Single registration point for provider metadata and per-type settings schemas. */
+export declare const WIDGET_SERVICE_PROVIDER_DEFINITIONS: {
+    rss: {
+        type: "rss";
+        kind: "news";
+        label: string;
+        settingsFields: {
+            key: string;
+            label: string;
+            input: "url";
+            required: true;
+            maxLength: number;
+            defaultValue: string;
+        }[];
+        secretSettingKeys: never[];
+        normalizeSettings: typeof normalizeRssSettings;
+    };
+    "open-meteo": {
+        type: "open-meteo";
+        kind: "weather";
+        label: string;
+        settingsFields: never[];
+        secretSettingKeys: never[];
+        normalizeSettings: typeof noSettings;
+    };
+    frankfurter: {
+        type: "frankfurter";
+        kind: "currency";
+        label: string;
+        settingsFields: never[];
+        secretSettingKeys: never[];
+        normalizeSettings: typeof noSettings;
+    };
+    "google-places": {
+        type: "google-places";
+        kind: "geo";
+        label: string;
+        settingsFields: {
+            key: string;
+            label: string;
+            input: "password";
+            required: true;
+            maxLength: number;
+        }[];
+        secretSettingKeys: "apiKey"[];
+        normalizeSettings: typeof normalizeGooglePlacesSettings;
+    };
+    coingecko: {
+        type: "coingecko";
+        kind: "crypto";
+        label: string;
+        settingsFields: {
+            key: string;
+            label: string;
+            input: "password";
+            required: false;
+            maxLength: number;
+        }[];
+        secretSettingKeys: "apiKey"[];
+        normalizeSettings: typeof normalizeCoingeckoSettings;
+    };
+    nasa: {
+        type: "nasa";
+        kind: "nasa";
+        label: string;
+        settingsFields: {
+            key: string;
+            label: string;
+            input: "password";
+            required: false;
+            maxLength: number;
+        }[];
+        secretSettingKeys: "apiKey"[];
+        normalizeSettings: typeof normalizeOptionalApiKey;
+    };
+};
+export declare const WIDGET_SERVICE_PROVIDER_TYPES: readonly (keyof WidgetServiceProviderSettingsMap)[];
+export declare function normalizeWidgetServiceProviderSettings<T extends WidgetServiceProviderType>(type: T, settings: WidgetServiceSettings): WidgetServiceProviderSettingsMap[T];
 export type WidgetServiceResult<T> = {
     ok: true;
     value: T;
@@ -16,7 +142,13 @@ export interface WidgetServiceProviderConfig {
     name: string;
     enabled: boolean;
     active: boolean;
-    settings: Record<string, string | number | boolean>;
+    settings: WidgetServiceSettings;
+}
+export interface WidgetServiceProviderPayload {
+    type: WidgetServiceProviderType;
+    name: string;
+    enabled: boolean;
+    settings: WidgetServiceSettings;
 }
 export interface NewsArticle {
     title: string;
@@ -53,4 +185,31 @@ export interface CurrencyRate {
     rate: number;
     date: string;
 }
+export interface CryptoQuote {
+    /** CoinGecko-style coin id, e.g. "bitcoin". */
+    coinId: string;
+    /** Display symbol, e.g. "BTC". */
+    symbol: string;
+    /** Price in `vsCurrency`. */
+    price: number;
+    /** Uppercase ISO 4217 code the price is quoted in. */
+    vsCurrency: string;
+    change24hPercent: number;
+    fetchedAt: string;
+}
+export interface CryptoBoard {
+    quotes: CryptoQuote[];
+    fetchedAt: string;
+}
+export interface AstronomyPictureOfTheDay {
+    date: string;
+    title: string;
+    explanation: string;
+    mediaType: "image" | "video";
+    url: string;
+    hdUrl?: string;
+    thumbnailUrl?: string;
+    copyright?: string;
+}
+export {};
 //# sourceMappingURL=widget-services.types.d.ts.map

package/dist/widget-services.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"widget-services.types.d.ts","sourceRoot":"","sources":["../src/widget-services.types.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;AAChE,MAAM,MAAM,yBAAyB,GAAG,KAAK,GAAG,YAAY,GAAG,aAAa,CAAC;AAE7E,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC,MAAM,WAAW,2BAA2B;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,yBAAyB,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"widget-services.types.d.ts","sourceRoot":"","sources":["../src/widget-services.types.ts"],"names":[],"mappings":"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"}

package/dist/widget-services.types.js

@@ -1,2 +1,138 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.WIDGET_SERVICE_PROVIDER_TYPES = exports.WIDGET_SERVICE_PROVIDER_DEFINITIONS = exports.WIDGET_SERVICE_SECRET_MASK = void 0;
+exports.normalizeWidgetServiceProviderSettings = normalizeWidgetServiceProviderSettings;
+exports.WIDGET_SERVICE_SECRET_MASK = "••••••••";
+function noSettings() {
+    return {};
+}
+function normalizeRssSettings(settings) {
+    const feedUrl = typeof settings.feedUrl === "string" ? settings.feedUrl.trim() : "";
+    let parsed;
+    try {
+        parsed = new URL(feedUrl);
+    }
+    catch {
+        throw new Error("RSS feed URL must be a valid HTTPS URL");
+    }
+    if (parsed.protocol !== "https:")
+        throw new Error("RSS feed URL must use HTTPS");
+    const hostname = parsed.hostname.toLowerCase();
+    if (hostname === "localhost" ||
+        hostname.endsWith(".localhost") ||
+        hostname.endsWith(".local") ||
+        hostname === "::1" ||
+        /^127\./.test(hostname) ||
+        /^10\./.test(hostname) ||
+        /^192\.168\./.test(hostname) ||
+        /^169\.254\./.test(hostname) ||
+        /^172\.(1[6-9]|2\d|3[01])\./.test(hostname)) {
+        throw new Error("RSS feed URL cannot target a local or private host");
+    }
+    return { feedUrl: parsed.toString() };
+}
+function normalizeGooglePlacesSettings(settings) {
+    const apiKey = typeof settings.apiKey === "string" ? settings.apiKey.trim() : "";
+    if (!apiKey || apiKey === exports.WIDGET_SERVICE_SECRET_MASK) {
+        throw new Error("Google Places API key is required");
+    }
+    return { apiKey };
+}
+function normalizeCoingeckoSettings(settings) {
+    const apiKey = typeof settings.apiKey === "string" ? settings.apiKey.trim() : "";
+    // The free tier needs no key; a surviving mask means no key was ever stored.
+    return apiKey && apiKey !== exports.WIDGET_SERVICE_SECRET_MASK ? { apiKey } : {};
+}
+function normalizeOptionalApiKey(settings) {
+    const apiKey = typeof settings.apiKey === "string" ? settings.apiKey.trim() : "";
+    return apiKey && apiKey !== exports.WIDGET_SERVICE_SECRET_MASK ? { apiKey } : {};
+}
+/** Single registration point for provider metadata and per-type settings schemas. */
+exports.WIDGET_SERVICE_PROVIDER_DEFINITIONS = {
+    rss: {
+        type: "rss",
+        kind: "news",
+        label: "RSS / Atom feed",
+        settingsFields: [
+            {
+                key: "feedUrl",
+                label: "Feed URL",
+                input: "url",
+                required: true,
+                maxLength: 2048,
+                defaultValue: "https://g1.globo.com/dynamo/rss2.xml",
+            },
+        ],
+        secretSettingKeys: [],
+        normalizeSettings: normalizeRssSettings,
+    },
+    "open-meteo": {
+        type: "open-meteo",
+        kind: "weather",
+        label: "Open-Meteo",
+        settingsFields: [],
+        secretSettingKeys: [],
+        normalizeSettings: noSettings,
+    },
+    frankfurter: {
+        type: "frankfurter",
+        kind: "currency",
+        label: "Frankfurter",
+        settingsFields: [],
+        secretSettingKeys: [],
+        normalizeSettings: noSettings,
+    },
+    "google-places": {
+        type: "google-places",
+        kind: "geo",
+        label: "Google Places",
+        settingsFields: [
+            {
+                key: "apiKey",
+                label: "API key",
+                input: "password",
+                required: true,
+                maxLength: 512,
+            },
+        ],
+        secretSettingKeys: ["apiKey"],
+        normalizeSettings: normalizeGooglePlacesSettings,
+    },
+    coingecko: {
+        type: "coingecko",
+        kind: "crypto",
+        label: "CoinGecko",
+        settingsFields: [
+            {
+                key: "apiKey",
+                label: "API key (optional)",
+                input: "password",
+                required: false,
+                maxLength: 512,
+            },
+        ],
+        secretSettingKeys: ["apiKey"],
+        normalizeSettings: normalizeCoingeckoSettings,
+    },
+    nasa: {
+        type: "nasa",
+        kind: "nasa",
+        label: "NASA Open APIs",
+        settingsFields: [
+            {
+                key: "apiKey",
+                label: "API key (optional; DEMO_KEY when empty)",
+                input: "password",
+                required: false,
+                maxLength: 512,
+            },
+        ],
+        secretSettingKeys: ["apiKey"],
+        normalizeSettings: normalizeOptionalApiKey,
+    },
+};
+exports.WIDGET_SERVICE_PROVIDER_TYPES = Object.freeze(Object.keys(exports.WIDGET_SERVICE_PROVIDER_DEFINITIONS));
+function normalizeWidgetServiceProviderSettings(type, settings) {
+    const definition = exports.WIDGET_SERVICE_PROVIDER_DEFINITIONS[type];
+    return definition.normalizeSettings(settings);
+}

package/dist/widget-services.types.spec.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const widget_services_types_1 = require("./widget-services.types");
 describe("widget service contracts", () => {
     it("uses a normalized result boundary for every provider", () => {
         const news = { ok: false, error: "offline" };
@@ -8,8 +9,63 @@ describe("widget service contracts", () => {
             value: { base: "USD", quote: "EUR", rate: 0.86, date: "2026-09-02" },
         };
         const weather = {};
+        const apod = {
+            date: "2026-09-04",
+            title: "The sky today",
+            explanation: "A test entry",
+            mediaType: "video",
+            url: "https://www.youtube.com/embed/example",
+        };
         expect(news.ok).toBe(false);
         expect(currency.ok).toBe(true);
         expect(weather).toEqual({});
+        expect(apod.mediaType).toBe("video");
+    });
+});
+describe("widget service provider definitions", () => {
+    it("registers every provider with its kind and settings schema", () => {
+        expect(widget_services_types_1.WIDGET_SERVICE_PROVIDER_TYPES).toEqual([
+            "rss",
+            "open-meteo",
+            "frankfurter",
+            "google-places",
+            "coingecko",
+            "nasa",
+        ]);
+        expect(widget_services_types_1.WIDGET_SERVICE_PROVIDER_DEFINITIONS["google-places"]).toMatchObject({
+            kind: "geo",
+            secretSettingKeys: ["apiKey"],
+        });
+        expect(widget_services_types_1.WIDGET_SERVICE_PROVIDER_DEFINITIONS.coingecko).toMatchObject({
+            kind: "crypto",
+            secretSettingKeys: ["apiKey"],
+        });
+        expect(widget_services_types_1.WIDGET_SERVICE_PROVIDER_DEFINITIONS.nasa).toMatchObject({
+            kind: "nasa",
+            secretSettingKeys: ["apiKey"],
+        });
+    });
+    it("keeps the CoinGecko API key optional", () => {
+        expect((0, widget_services_types_1.normalizeWidgetServiceProviderSettings)("coingecko", { apiKey: " k-1 " })).toEqual({ apiKey: "k-1" });
+        expect((0, widget_services_types_1.normalizeWidgetServiceProviderSettings)("coingecko", {})).toEqual({});
+        expect((0, widget_services_types_1.normalizeWidgetServiceProviderSettings)("coingecko", { apiKey: "" })).toEqual({});
+    });
+    it("keeps the NASA API key optional and trims configured keys", () => {
+        expect((0, widget_services_types_1.normalizeWidgetServiceProviderSettings)("nasa", {})).toEqual({});
+        expect((0, widget_services_types_1.normalizeWidgetServiceProviderSettings)("nasa", { apiKey: " nasa-key " })).toEqual({ apiKey: "nasa-key" });
+    });
+    it("normalizes settings through the selected provider schema", () => {
+        expect((0, widget_services_types_1.normalizeWidgetServiceProviderSettings)("rss", {
+            feedUrl: " https://example.com/feed.xml ",
+        })).toEqual({ feedUrl: "https://example.com/feed.xml" });
+        expect((0, widget_services_types_1.normalizeWidgetServiceProviderSettings)("open-meteo", { ignored: true })).toEqual({});
+    });
+    it("rejects unsafe RSS URLs and masked secrets", () => {
+        expect(() => (0, widget_services_types_1.normalizeWidgetServiceProviderSettings)("rss", {
+            feedUrl: "https://localhost/feed",
+        })).toThrow("local or private host");
+        expect(() => (0, widget_services_types_1.normalizeWidgetServiceProviderSettings)("google-places", {
+            apiKey: widget_services_types_1.WIDGET_SERVICE_SECRET_MASK,
+        })).toThrow("API key is required");
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guinetik/primitives-ts",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Shared TypeScript primitives for Guinetik projects",
   "author": "Guinetik",
   "license": "MIT",