@guinetik/primitives-ts 0.13.0 → 0.14.1

package/dist/email.types.d.ts

@@ -75,20 +75,30 @@ export interface EmailVerifyResult {
     ok: boolean;
     error?: string;
 }
+export type ApiKeyScope = 'email:send' | 'geo';
 /** API key metadata — never contains the full key. */
-export interface EmailApiKey {
+export interface ApiKey {
     id: string;
     name: string;
     /** Free-form attribution label (e.g. agents@guinetik.com). Not an account link. */
     owner?: string;
+    scopes: ApiKeyScope[];
     prefix: string;
     createdAt: string;
     lastUsedAt?: string;
 }
 /** Returned once, at creation time only. */
-export interface EmailApiKeyCreated extends EmailApiKey {
+export interface ApiKeyCreated extends ApiKey {
     key: string;
 }
+/** @deprecated Use {@link ApiKey}. */
+export type EmailApiKey = Omit<ApiKey, 'scopes'> & {
+    scopes?: ApiKeyScope[];
+};
+/** @deprecated Use {@link ApiKeyCreated}. */
+export type EmailApiKeyCreated = EmailApiKey & {
+    key: string;
+};
 /** email-providers doc. Secret fields stored as enc:v1:... strings. */
 export interface EmailProviderDocument extends FirestoreDocument {
     type: EmailProviderType;
@@ -108,4 +118,13 @@ export interface EmailApiKeyDocument extends FirestoreDocument {
     prefix: string;
     lastUsedAt?: Date;
 }
+/** api-keys doc (shared collection, replaces email-api-keys). */
+export interface ApiKeyDocument extends FirestoreDocument {
+    name: string;
+    owner?: string;
+    scopes: ApiKeyScope[];
+    keyHash: string;
+    prefix: string;
+    lastUsedAt?: Date;
+}
 //# sourceMappingURL=email.types.d.ts.map

package/dist/email.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"email.types.d.ts","sourceRoot":"","sources":["../src/email.types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"email.types.d.ts","sourceRoot":"","sources":["../src/email.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,0CAA0C;AAC1C,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,YAAY,GAAG,MAAM,CAAC;AAEjE,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,4CAA4C;AAC5C,MAAM,WAAW,cAAe,SAAQ,yBAAyB;IAC/D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,oDAAoD;AACpD,MAAM,WAAW,kBAAmB,SAAQ,yBAAyB;IACnE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAa,SAAQ,yBAAyB;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,qBAAqB,GAAG,cAAc,GAAG,kBAAkB,GAAG,YAAY,CAAC;AAEvF,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,qBAAqB,CAAC;CACjC;AAED,gEAAgE;AAChE,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,2BAA2B,CAAC;IACtC,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,KAAK,CAAC;AAE/C,sDAAsD;AACtD,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAc,SAAQ,MAAM;IAC3C,GAAG,EAAE,MAAM,CAAC;CACb;AAED,sCAAsC;AACtC,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,WAAW,EAAE,CAAA;CAAE,CAAC;AAC9E,6CAA6C;AAC7C,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAM/D,uEAAuE;AACvE,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACrD;AAED,oCAAoC;AACpC,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,0BAA0B;AAC1B,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB;AAED,iEAAiE;AACjE,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB"}

package/dist/geo.types.d.ts

@@ -0,0 +1,19 @@
+/** A resolved place from the geo autocomplete service. */
+export interface GeoLocation {
+    /** Display name as picked, e.g. "São José da Coroa Grande". */
+    name: string;
+    /** Secondary line, e.g. "Pernambuco, Brazil". */
+    region?: string;
+    lat: number;
+    lon: number;
+    /** IANA zone id derived server-side, e.g. "America/Recife". */
+    timeZone: string;
+    /** Google place id when resolved through Places. */
+    placeId?: string;
+}
+/** One autocomplete prediction; resolve via /geo/place/:placeId. */
+export interface GeoSuggestion {
+    placeId: string;
+    description: string;
+}
+//# sourceMappingURL=geo.types.d.ts.map

package/dist/geo.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geo.types.d.ts","sourceRoot":"","sources":["../src/geo.types.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/geo.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -1,19 +1,61 @@
-export type HomeWidgetType = 'launchpad' | 'clock' | 'webpage';
+import type { GeoLocation } from "./geo.types";
+export type HomeWidgetType = "launchpad" | "clock" | "webpage" | "analytics" | "utility" | "news" | "weather" | "currency";
 export type HomeWidgetColSpan = 1 | 2 | 3;
 export interface LaunchpadWidgetConfig {
+    /** Launchpad group ids to show. Omitted on legacy widgets means all groups. */
+    groupIds?: string[];
 }
 export interface ClockWidgetConfig {
     timeZone: string;
     preset: string;
     /** Display the time on a 12-hour clock. Defaults to 24-hour when absent. */
     hour12?: boolean;
+    /** Resolved place. Legacy widgets have only timeZone. */
+    location?: GeoLocation;
 }
 export interface WebpageWidgetConfig {
     url: string;
 }
-export type HomeWidgetConfig = LaunchpadWidgetConfig | ClockWidgetConfig | WebpageWidgetConfig;
+export interface AnalyticsWidgetConfig {
+    /** Saved GA4 property resource name, e.g. `properties/123456`. */
+    propertyId: string;
+}
+export declare const UTILITY_TOOL_IDS: readonly ["unit-converter", "text-workbench", "date-calculator"];
+export type UtilityToolId = (typeof UTILITY_TOOL_IDS)[number];
+/**
+ * Persisted utility selection and defaults. Interactive values remain local
+ * to the widget and are deliberately not written on every keystroke.
+ */
+export interface UtilityWidgetConfig {
+    schemaVersion: 1;
+    toolId: UtilityToolId;
+    settings: Record<string, unknown>;
+}
+export interface NewsWidgetConfig {
+    /** Enabled provider to use. Omitted means the category default. */
+    providerId?: string;
+    limit: number;
+    /** Automatic feed refresh cadence in minutes. Omitted means 15 minutes. */
+    refreshMinutes?: number;
+}
+export interface WeatherWidgetConfig {
+    /** Enabled provider to use. Omitted means the category default. */
+    providerId?: string;
+    /** Resolved place; plain string on legacy widgets. */
+    location: string | GeoLocation;
+}
+export interface CurrencyWidgetConfig {
+    /** Enabled provider to use. Omitted means the category default. */
+    providerId?: string;
+    base: string;
+    quote: string;
+    defaultAmount: number;
+}
+export type HomeWidgetConfig = LaunchpadWidgetConfig | ClockWidgetConfig | WebpageWidgetConfig | AnalyticsWidgetConfig | UtilityWidgetConfig | NewsWidgetConfig | WeatherWidgetConfig | CurrencyWidgetConfig;
 export interface HomeDashboardWidget {
     id: string;
+    /** Optional user-defined chrome title. The widget type is used when omitted. */
+    title?: string;
     type: HomeWidgetType;
     colSpan: HomeWidgetColSpan;
     order: number;
@@ -27,6 +69,8 @@ export declare const HOME_WIDGET_TYPES: readonly HomeWidgetType[];
 export declare const MAX_HOME_WIDGETS = 30;
 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"];
+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,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,CAAC;AAE/D,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAE1C,MAAM,WAAW,qBAAqB;CAErC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,gBAAgB,GACxB,qBAAqB,GACrB,iBAAiB,GACjB,mBAAmB,CAAC;AAExB,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,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,EAItD,CAAC;AAEF,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAE1D,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAE7C,eAAO,MAAM,aAAa,uCAAwC,CAAC;AAEnE,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,16 +1,192 @@
 "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 = void 0;
+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.isHomeWidgetType = isHomeWidgetType;
+exports.validateHomeWidgetConfig = validateHomeWidgetConfig;
+exports.UTILITY_TOOL_IDS = [
+    "unit-converter",
+    "text-workbench",
+    "date-calculator",
+];
 exports.HOME_WIDGET_TYPES = [
-    'launchpad',
-    'clock',
-    'webpage',
+    "launchpad",
+    "clock",
+    "webpage",
+    "analytics",
+    "utility",
+    "news",
+    "weather",
+    "currency",
 ];
 exports.MAX_HOME_WIDGETS = 30;
-exports.CLOCK_DEFAULT_TIMEZONE = 'America/Sao_Paulo';
-exports.CLOCK_DEFAULT_PRESET = 'aurora';
-exports.CLOCK_PRESETS = ['aurora', 'grid', 'binary'];
+exports.CLOCK_DEFAULT_TIMEZONE = "America/Sao_Paulo";
+exports.CLOCK_DEFAULT_PRESET = "aurora";
+exports.CLOCK_PRESETS = [
+    "aurora",
+    "grid",
+    "binary",
+    "day-night",
+    "location-photos",
+];
 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;
+    },
+};
+function validateHomeWidgetConfig(type, config) {
+    return HOME_WIDGET_CONFIG_VALIDATORS[type](config);
+}

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

@@ -2,33 +2,160 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const website_firestore_types_1 = require("./website-firestore.types");
 const home_dashboard_types_1 = require("./home-dashboard.types");
-describe('home dashboard types', () => {
-    it('registers the Firestore collection', () => {
-        expect(website_firestore_types_1.FIRESTORE_COLLECTIONS.HOME_DASHBOARDS).toBe('home-dashboards');
+describe("home dashboard types", () => {
+    it("registers the Firestore collection", () => {
+        expect(website_firestore_types_1.FIRESTORE_COLLECTIONS.HOME_DASHBOARDS).toBe("home-dashboards");
     });
-    it('accepts the three shipped types and rejects unknown ones', () => {
-        expect(home_dashboard_types_1.HOME_WIDGET_TYPES).toEqual(['launchpad', 'clock', 'webpage']);
-        expect((0, home_dashboard_types_1.isHomeWidgetType)('clock')).toBe(true);
-        expect((0, home_dashboard_types_1.isHomeWidgetType)('weather')).toBe(false);
+    it("accepts the shipped types and rejects unknown ones", () => {
+        expect(home_dashboard_types_1.HOME_WIDGET_TYPES).toEqual([
+            "launchpad",
+            "clock",
+            "webpage",
+            "analytics",
+            "utility",
+            "news",
+            "weather",
+            "currency",
+        ]);
+        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)("stock-ticker")).toBe(false);
     });
-    it('caps a board at 30 widgets and defaults the clock', () => {
+    it("stores a versioned allowlisted utility configuration", () => {
+        const widget = {
+            id: "utility-1",
+            type: "utility",
+            colSpan: 2,
+            order: 0,
+            config: {
+                schemaVersion: 1,
+                toolId: "unit-converter",
+                settings: {
+                    category: "length",
+                    from: "meter",
+                    to: "foot",
+                    precision: 2,
+                },
+            },
+        };
+        expect(widget.config).toMatchObject({
+            schemaVersion: 1,
+            toolId: "unit-converter",
+        });
+    });
+    it("caps a board at 30 widgets and defaults the clock", () => {
         expect(home_dashboard_types_1.MAX_HOME_WIDGETS).toBe(30);
-        expect(home_dashboard_types_1.CLOCK_DEFAULT_TIMEZONE).toBe('America/Sao_Paulo');
-        expect(home_dashboard_types_1.CLOCK_DEFAULT_PRESET).toBe('aurora');
+        expect(home_dashboard_types_1.CLOCK_DEFAULT_TIMEZONE).toBe("America/Sao_Paulo");
+        expect(home_dashboard_types_1.CLOCK_DEFAULT_PRESET).toBe("aurora");
+    });
+    it("allows launchpad widgets to select groups while keeping legacy config valid", () => {
+        const legacy = {};
+        const selected = {
+            groupIds: ["infra", "publishing"],
+        };
+        expect(legacy.groupIds).toBeUndefined();
+        expect(selected.groupIds).toEqual(["infra", "publishing"]);
+    });
+    it("allows a widget to carry a custom title", () => {
+        const widget = {
+            id: "clock-1",
+            title: "São Paulo",
+            type: "clock",
+            colSpan: 1,
+            order: 0,
+            config: { timeZone: "America/Sao_Paulo", preset: "aurora" },
+        };
+        expect(widget.title).toBe("São Paulo");
+    });
+    it("stores the selected property on an Analytics widget", () => {
+        const widget = {
+            id: "analytics-1",
+            type: "analytics",
+            colSpan: 2,
+            order: 0,
+            config: { propertyId: "properties/123456" },
+        };
+        expect(widget.config).toEqual({ propertyId: "properties/123456" });
+    });
+    it("stores a news refresh cadence while keeping legacy configs valid", () => {
+        const legacy = { limit: 5 };
+        const refreshing = { limit: 5, refreshMinutes: 30 };
+        expect(legacy.refreshMinutes).toBeUndefined();
+        expect(refreshing.refreshMinutes).toBe(30);
     });
 });
-describe('clock presets', () => {
-    it('includes the binary preset', () => {
-        expect(home_dashboard_types_1.CLOCK_PRESETS).toContain('binary');
+describe("clock presets", () => {
+    it("includes the location-aware backgrounds", () => {
+        expect(home_dashboard_types_1.CLOCK_PRESETS).toContain("day-night");
+        expect(home_dashboard_types_1.CLOCK_PRESETS).toContain("location-photos");
+    });
+    it("includes the binary preset", () => {
+        expect(home_dashboard_types_1.CLOCK_PRESETS).toContain("binary");
     });
-    it('keeps aurora as the default and a member of the list', () => {
-        expect(home_dashboard_types_1.CLOCK_DEFAULT_PRESET).toBe('aurora');
+    it("keeps aurora as the default and a member of the list", () => {
+        expect(home_dashboard_types_1.CLOCK_DEFAULT_PRESET).toBe("aurora");
         expect(home_dashboard_types_1.CLOCK_PRESETS).toContain(home_dashboard_types_1.CLOCK_DEFAULT_PRESET);
     });
-    it('allows an optional hour12 flag on a clock config', () => {
-        const twentyFour = { timeZone: 'UTC', preset: 'grid' };
-        const twelve = { timeZone: 'UTC', preset: 'grid', hour12: true };
+    it("allows an optional hour12 flag on a clock config", () => {
+        const twentyFour = { timeZone: "UTC", preset: "grid" };
+        const twelve = {
+            timeZone: "UTC",
+            preset: "grid",
+            hour12: true,
+        };
         expect(twentyFour.hour12).toBeUndefined();
         expect(twelve.hour12).toBe(true);
     });
 });
+describe("GeoLocation", () => {
+    it("accepts a resolved place and is assignable into widget configs", () => {
+        const loc = {
+            name: "São José da Coroa Grande",
+            region: "Pernambuco, Brazil",
+            lat: -8.8978,
+            lon: -35.1478,
+            timeZone: "America/Recife",
+            placeId: "ChIJexample",
+        };
+        const clock = {
+            timeZone: loc.timeZone,
+            preset: "aurora",
+            location: loc,
+        };
+        const weather = { location: loc };
+        expect(clock.location?.lat).toBeCloseTo(-8.8978);
+        expect(typeof weather.location === "string" ? "" : weather.location.name).toContain("Coroa");
+    });
+    it("weather still accepts a legacy string location", () => {
+        const weather = { location: "Cayenne" };
+        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/index.d.ts

@@ -22,8 +22,10 @@ export * from './agent.types';
 export * from './file.types';
 export * from './launchpad.types';
 export * from './home-dashboard.types';
+export * from './geo.types';
 export * from './email.types';
 export * from './analytics.types';
+export * from './widget-services.types';
 export type { Security, SecurityChallengeOptions, SecurityChallengeResult } from './security.interface';
 export { SecurityLevel } from './security.interface';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,cAAc,cAAc,CAAC;AAG7B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,cAAc,CAAC;AAG7B,cAAc,4BAA4B,CAAC;AAG3C,cAAc,gBAAgB,CAAC;AAG/B,cAAc,cAAc,CAAC;AAG7B,cAAc,eAAe,CAAC;AAG9B,cAAc,eAAe,CAAC;AAG9B,cAAc,cAAc,CAAC;AAG7B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,eAAe,CAAC;AAG9B,cAAc,mBAAmB,CAAC;AAGlC,YAAY,EAAE,QAAQ,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACxG,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,cAAc,cAAc,CAAC;AAG7B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,cAAc,CAAC;AAG7B,cAAc,4BAA4B,CAAC;AAG3C,cAAc,gBAAgB,CAAC;AAG/B,cAAc,cAAc,CAAC;AAG7B,cAAc,eAAe,CAAC;AAG9B,cAAc,eAAe,CAAC;AAG9B,cAAc,cAAc,CAAC;AAG7B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,aAAa,CAAC;AAG5B,cAAc,eAAe,CAAC;AAG9B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,yBAAyB,CAAC;AAGxC,YAAY,EAAE,QAAQ,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACxG,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -54,9 +54,13 @@ __exportStar(require("./file.types"), exports);
 __exportStar(require("./launchpad.types"), exports);
 // Per-user home dashboard widget types
 __exportStar(require("./home-dashboard.types"), exports);
+// Geo autocomplete types
+__exportStar(require("./geo.types"), exports);
 // Email module types
 __exportStar(require("./email.types"), exports);
 // Google Analytics portal types
 __exportStar(require("./analytics.types"), exports);
+// Provider-backed dashboard widget types
+__exportStar(require("./widget-services.types"), exports);
 var security_interface_1 = require("./security.interface");
 Object.defineProperty(exports, "SecurityLevel", { enumerable: true, get: function () { return security_interface_1.SecurityLevel; } });

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

@@ -0,0 +1,149 @@
+/** Shared contracts for provider-backed dashboard widgets. */
+export type WidgetServiceKind = "news" | "weather" | "currency" | "geo";
+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;
+    };
+}
+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;
+};
+/** 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;
+    };
+};
+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;
+    message?: string;
+} | {
+    ok: false;
+    error: string;
+};
+export interface WidgetServiceProviderConfig {
+    id: string;
+    kind: WidgetServiceKind;
+    type: WidgetServiceProviderType;
+    name: string;
+    enabled: boolean;
+    active: boolean;
+    settings: WidgetServiceSettings;
+}
+export interface WidgetServiceProviderPayload {
+    type: WidgetServiceProviderType;
+    name: string;
+    enabled: boolean;
+    settings: WidgetServiceSettings;
+}
+export interface NewsArticle {
+    title: string;
+    description: string;
+    url: string;
+    imageUrl?: string;
+    publishedAt?: string;
+    source: string;
+}
+export interface NewsFeed {
+    source: string;
+    articles: NewsArticle[];
+    fetchedAt: string;
+}
+export interface WeatherSnapshot {
+    location: string;
+    latitude: number;
+    longitude: number;
+    temperatureC: number;
+    apparentTemperatureC: number;
+    humidityPercent: number;
+    precipitationMm: number;
+    pressureHpa: number;
+    cloudCoverPercent: number;
+    windSpeedKph: number;
+    windDirectionDegrees: number;
+    weatherCode: number;
+    description: string;
+    observedAt: string;
+}
+export interface CurrencyRate {
+    base: string;
+    quote: string;
+    rate: number;
+    date: string;
+}
+export {};
+//# sourceMappingURL=widget-services.types.d.ts.map

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

@@ -0,0 +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,GAAG,KAAK,CAAC;AAExE,MAAM,MAAM,yBAAyB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAClE,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;AAE9E,MAAM,WAAW,gCAAgC;IAC/C,GAAG,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACnC,eAAe,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACrC;AAED,MAAM,MAAM,yBAAyB,GAAG,MAAM,gCAAgC,CAAC;AAE/E,MAAM,WAAW,0BAA0B;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,+BAA+B,CAC9C,CAAC,SAAS,yBAAyB;IAEnC,IAAI,EAAE,CAAC,CAAC;IACR,IAAI,EAAE,iBAAiB,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,SAAS,0BAA0B,EAAE,CAAC;IACtD,iBAAiB,EAAE,SAAS,CAAC,MAAM,gCAAgC,CAAC,CAAC,CAAC,GACpE,MAAM,CAAC,EAAE,CAAC;IACZ,iBAAiB,CACf,QAAQ,EAAE,qBAAqB,GAC9B,gCAAgC,CAAC,CAAC,CAAC,CAAC;CACxC;AAED,eAAO,MAAM,0BAA0B,qDAAa,CAAC;AAErD,iBAAS,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAE3C;AAED,iBAAS,oBAAoB,CAAC,QAAQ,EAAE,qBAAqB,GAAG;IAC9D,OAAO,EAAE,MAAM,CAAC;CACjB,CA0BA;AAED,iBAAS,6BAA6B,CAAC,QAAQ,EAAE,qBAAqB,GAAG;IACvE,MAAM,EAAE,MAAM,CAAC;CAChB,CAOA;AAED,qFAAqF;AACrF,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoD/C,CAAC;AAEF,eAAO,MAAM,6BAA6B,qDAIzC,CAAC;AAEF,wBAAgB,sCAAsC,CACpD,CAAC,SAAS,yBAAyB,EAEnC,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,qBAAqB,GAC9B,gCAAgC,CAAC,CAAC,CAAC,CAKrC;AAED,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,qBAAqB,CAAC;CACjC;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,yBAAyB,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,qBAAqB,CAAC;CACjC;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"}

package/dist/widget-services.types.js

@@ -0,0 +1,97 @@
+"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 };
+}
+/** 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,
+    },
+};
+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.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=widget-services.types.spec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"widget-services.types.spec.d.ts","sourceRoot":"","sources":["../src/widget-services.types.spec.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,44 @@
+"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" };
+        const currency = {
+            ok: true,
+            value: { base: "USD", quote: "EUR", rate: 0.86, date: "2026-09-02" },
+        };
+        const weather = {};
+        expect(news.ok).toBe(false);
+        expect(currency.ok).toBe(true);
+        expect(weather).toEqual({});
+    });
+});
+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",
+        ]);
+        expect(widget_services_types_1.WIDGET_SERVICE_PROVIDER_DEFINITIONS["google-places"]).toMatchObject({
+            kind: "geo",
+            secretSettingKeys: ["apiKey"],
+        });
+    });
+    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.13.0",
+  "version": "0.14.1",
   "description": "Shared TypeScript primitives for Guinetik projects",
   "author": "Guinetik",
   "license": "MIT",