adaria-ai 0.1.0

package/dist/collectors/eodin-sdk.js

@@ -0,0 +1,112 @@
+import { ExternalApiError } from "../utils/errors.js";
+const ALLOWED_HOSTS = new Set(["api.eodin.app"]);
+const DEFAULT_BASE_URL = "https://api.eodin.app/api/v1/events";
+const ERROR_BODY_MAX_CHARS = 512;
+export class EodinSdkCollector {
+    apiKey;
+    baseUrl;
+    loggedPercentCohort = false;
+    constructor(options, testHooks) {
+        if (!options.apiKey) {
+            throw new Error("EodinSdkCollector requires apiKey");
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = testHooks?.baseUrl ?? DEFAULT_BASE_URL;
+    }
+    async request(path, params = {}) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (!ALLOWED_HOSTS.has(url.hostname)) {
+            throw new Error(`Untrusted SDK host: ${url.hostname}. Allowed: ${[...ALLOWED_HOSTS].join(", ")}`);
+        }
+        for (const [key, value] of Object.entries(params)) {
+            // `null` is a defensive check for loose callers even though QueryParams
+            // doesn't declare it — leave both branches in.
+            if (value === undefined || value === null || value === "")
+                continue;
+            url.searchParams.set(key, String(value));
+        }
+        const response = await fetch(url.toString(), {
+            headers: {
+                "X-API-Key": this.apiKey,
+                "Content-Type": "application/json",
+            },
+        });
+        if (!response.ok) {
+            const rawBody = await response.text();
+            // The Eodin server has historically echoed the submitted API key back
+            // in error bodies (`{"error":"Invalid X-API-Key: <key>"}`). Redact
+            // before the message reaches audit logs or Slack error cards.
+            const redacted = rawBody
+                .replaceAll(this.apiKey, "[REDACTED]")
+                .slice(0, ERROR_BODY_MAX_CHARS);
+            throw new ExternalApiError(`Eodin SDK API ${String(response.status)}: ${redacted}`, { statusCode: response.status });
+        }
+        return (await response.json());
+    }
+    /**
+     * Daily/weekly/monthly aggregate rows.
+     */
+    async getSummary(appId, startDate, endDate, options = {}) {
+        const res = await this.request("/summary", {
+            app_id: appId,
+            start: startDate,
+            end: endDate,
+            granularity: options.granularity ?? "daily",
+            os: options.os ?? "all",
+        });
+        return res.data ?? [];
+    }
+    /**
+     * Aggregate funnel for the period. Step order is fixed by the Eodin API:
+     * `app_install → app_open → core_action → paywall_view → subscribe_start`.
+     */
+    async getFunnel(appId, startDate, endDate, options = {}) {
+        const res = await this.request("/funnel", {
+            app_id: appId,
+            start: startDate,
+            end: endDate,
+            source: options.source,
+            os: options.os ?? "all",
+        });
+        return res.data ?? { funnel: [], overall_conversion: 0 };
+    }
+    /**
+     * Cohort retention. `retention[0]` is always the cohort anchor (100% of
+     * the cohort by definition), so any value above 1.5 signals the server
+     * returned percents instead of fractions; we detect and normalize so
+     * every downstream consumer sees fractions in [0, 1].
+     */
+    async getCohort(appId, startDate, endDate, options = {}) {
+        const res = await this.request("/cohort", {
+            app_id: appId,
+            start: startDate,
+            end: endDate,
+            granularity: options.granularity ?? "weekly",
+            os: options.os ?? "all",
+        });
+        const cohorts = res.data?.cohorts ?? [];
+        return cohorts.map((c) => ({
+            ...c,
+            retention: this.normalizeRetention(c.retention),
+        }));
+    }
+    normalizeRetention(retention) {
+        // Wire is typed as number[] but the Eodin server has historically
+        // returned nulls/strings inside the array, so the typeof guards below
+        // are intentional runtime defense — not dead code the strict types
+        // would otherwise suggest.
+        if (!Array.isArray(retention) || retention.length === 0) {
+            return retention;
+        }
+        const first = retention[0];
+        if (typeof first !== "number" || first <= 1.5) {
+            return retention;
+        }
+        if (!this.loggedPercentCohort) {
+            console.warn("[eodin-sdk] Detected percent-encoded cohort retention; normalizing to fractions.");
+            this.loggedPercentCohort = true;
+        }
+        return retention.map((r) => (typeof r === "number" ? r / 100 : r));
+    }
+}
+//# sourceMappingURL=eodin-sdk.js.map

package/dist/collectors/eodin-sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eodin-sdk.js","sourceRoot":"","sources":["../../src/collectors/eodin-sdk.ts"],"names":[],"mappings":"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"}

package/dist/collectors/fridgify-recipes.d.ts

@@ -0,0 +1,65 @@
+import type { FridgifyCascadeResult, FridgifyPeriod, FridgifyPopularMetric, FridgifyRecipe } from "../types/collectors.js";
+/**
+ * Fridgify Recipes API collector.
+ *
+ * Thin wrapper around the Fridgify backend's public recipe endpoints that
+ * power the growth agent's recipe-aware blog posts.
+ *
+ * - Base URL: `https://fridgify-api.eodin.app`
+ * - Auth: none (public endpoints, IP rate-limited 20 req/min)
+ */
+export interface FridgifyRecipesCollectorOptions {
+    /** Override the rate-limit backoff window. Defaults to 60 s. */
+    retryDelayMs?: number;
+}
+/**
+ * Test-only overrides. `baseUrl` stays off the production options type so
+ * config loaders cannot introduce a user-controlled URL into the SSRF
+ * surface; the allowlist still applies to test-hook values.
+ */
+export interface FridgifyRecipesCollectorTestHooks {
+    baseUrl?: string;
+}
+export interface GetPopularOptions {
+    period?: FridgifyPeriod;
+    metric?: FridgifyPopularMetric;
+    /** Server clamps to 1–50. */
+    limit?: number;
+}
+export interface CascadeOptions {
+    metric?: FridgifyPopularMetric;
+    limit?: number;
+    /** Narrowest window is accepted once `rows.length >= minResults`. */
+    minResults?: number;
+}
+export declare class FridgifyRecipesCollector {
+    private readonly baseUrl;
+    private readonly retryDelayMs;
+    constructor(options?: FridgifyRecipesCollectorOptions, testHooks?: FridgifyRecipesCollectorTestHooks);
+    private fetchOnce;
+    private request;
+    /**
+     * Top recipes in a time window, ranked by engagement.
+     */
+    getPopular(options?: GetPopularOptions): Promise<FridgifyRecipe[]>;
+    /**
+     * Period-cascade variant of {@link getPopular}.
+     *
+     * Fridgify's `week` window is frequently empty under current traffic.
+     * Walk week → month → quarter → year and stop at the narrowest window
+     * that yields at least `minResults` rows, so blog copy naturally stays
+     * fresh ("Top recipes this week") without the skill giving up when the
+     * week is quiet.
+     *
+     * Callers that need a roundup-worthy result should branch on
+     * {@link FridgifyCascadeResult.satisfied}, not on `rows.length > 0`, to
+     * avoid building a "top recipes this year" post from a single stray row.
+     */
+    getPopularWithCascade(options?: CascadeOptions): Promise<FridgifyCascadeResult>;
+    /**
+     * Fetch a single recipe by id. Returns the same shape as items in
+     * {@link getPopular} minus `periodScore`.
+     */
+    getRecipe(id: string): Promise<FridgifyRecipe>;
+}
+//# sourceMappingURL=fridgify-recipes.d.ts.map

package/dist/collectors/fridgify-recipes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fridgify-recipes.d.ts","sourceRoot":"","sources":["../../src/collectors/fridgify-recipes.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,qBAAqB,EACrB,cAAc,EACd,qBAAqB,EACrB,cAAc,EACf,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;GAQG;AACH,MAAM,WAAW,+BAA+B;IAC9C,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,iCAAiC;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAcD,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAGpC,OAAO,GAAE,+BAAoC,EAC7C,SAAS,CAAC,EAAE,iCAAiC;YAMjC,SAAS;YAMT,OAAO;IAmDrB;;OAEG;IACG,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAa5E;;;;;;;;;;;;OAYG;IACG,qBAAqB,CACzB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,qBAAqB,CAAC;IA0BjC;;;OAGG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;CAUrD"}

package/dist/collectors/fridgify-recipes.js

@@ -0,0 +1,111 @@
+import { ExternalApiError, RateLimitError } from "../utils/errors.js";
+import { info as logInfo, warn as logWarn } from "../utils/logger.js";
+const DEFAULT_BASE_URL = "https://fridgify-api.eodin.app";
+const DEFAULT_RETRY_DELAY_MS = 60_000;
+const ALLOWED_HOSTS = new Set([
+    "fridgify-api.eodin.app",
+]);
+const CASCADE_PERIODS = [
+    "week",
+    "month",
+    "quarter",
+    "year",
+];
+export class FridgifyRecipesCollector {
+    baseUrl;
+    retryDelayMs;
+    constructor(options = {}, testHooks) {
+        this.baseUrl = testHooks?.baseUrl ?? DEFAULT_BASE_URL;
+        this.retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+    }
+    async fetchOnce(url) {
+        return fetch(url, {
+            headers: { "Content-Type": "application/json" },
+        });
+    }
+    async request(path, params = {}) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (!ALLOWED_HOSTS.has(url.hostname)) {
+            throw new Error(`Untrusted Fridgify host: ${url.hostname}. Allowed: ${[...ALLOWED_HOSTS].join(", ")}`);
+        }
+        for (const [key, value] of Object.entries(params)) {
+            if (value === undefined || value === "")
+                continue;
+            url.searchParams.set(key, String(value));
+        }
+        const target = url.toString();
+        let response = await this.fetchOnce(target);
+        // The endpoint is capped at 20 req/min per IP. Retry exactly once after
+        // the configured backoff so scheduled weekly runs can ride through a
+        // bursty neighbor on the shared IP. Retrying more aggressively would
+        // just waste the budget.
+        if (response.status === 429) {
+            logWarn(`[fridgify-recipes] 429 on ${path}; waiting ${String(this.retryDelayMs)}ms before one retry`);
+            await new Promise((resolve) => setTimeout(resolve, this.retryDelayMs));
+            response = await this.fetchOnce(target);
+        }
+        if (!response.ok) {
+            const body = await response.text();
+            if (response.status === 429) {
+                throw new RateLimitError(`Fridgify API still rate limited after 1 retry: ${body.slice(0, 512)}`, { retryAfterSeconds: Math.ceil(this.retryDelayMs / 1000) });
+            }
+            throw new ExternalApiError(`Fridgify API ${String(response.status)}: ${body.slice(0, 512)}`, { statusCode: response.status });
+        }
+        return (await response.json());
+    }
+    /**
+     * Top recipes in a time window, ranked by engagement.
+     */
+    async getPopular(options = {}) {
+        const period = options.period ?? "week";
+        const metric = options.metric ?? "combined";
+        const limit = options.limit ?? 10;
+        const data = await this.request("/recipes/popular", {
+            period,
+            metric,
+            limit,
+        });
+        return Array.isArray(data) ? data : [];
+    }
+    /**
+     * Period-cascade variant of {@link getPopular}.
+     *
+     * Fridgify's `week` window is frequently empty under current traffic.
+     * Walk week → month → quarter → year and stop at the narrowest window
+     * that yields at least `minResults` rows, so blog copy naturally stays
+     * fresh ("Top recipes this week") without the skill giving up when the
+     * week is quiet.
+     *
+     * Callers that need a roundup-worthy result should branch on
+     * {@link FridgifyCascadeResult.satisfied}, not on `rows.length > 0`, to
+     * avoid building a "top recipes this year" post from a single stray row.
+     */
+    async getPopularWithCascade(options = {}) {
+        const metric = options.metric ?? "combined";
+        const limit = options.limit ?? 10;
+        const minResults = options.minResults ?? 5;
+        let lastRows = [];
+        for (const period of CASCADE_PERIODS) {
+            const rows = await this.getPopular({ period, metric, limit });
+            lastRows = rows;
+            if (rows.length >= minResults) {
+                logInfo(`[fridgify-recipes] cascade stopped at period=${period} (${String(rows.length)} rows)`);
+                return { period, rows, satisfied: true };
+            }
+        }
+        const finalPeriod = CASCADE_PERIODS[CASCADE_PERIODS.length - 1] ?? "year";
+        logWarn(`[fridgify-recipes] cascade exhausted — no window had >=${String(minResults)} rows (last=${String(lastRows.length)})`);
+        return { period: finalPeriod, rows: lastRows, satisfied: false };
+    }
+    /**
+     * Fetch a single recipe by id. Returns the same shape as items in
+     * {@link getPopular} minus `periodScore`.
+     */
+    async getRecipe(id) {
+        if (id.length === 0) {
+            throw new Error("FridgifyRecipesCollector.getRecipe requires a non-empty string id");
+        }
+        return this.request(`/recipes/${encodeURIComponent(id)}`);
+    }
+}
+//# sourceMappingURL=fridgify-recipes.js.map

package/dist/collectors/fridgify-recipes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fridgify-recipes.js","sourceRoot":"","sources":["../../src/collectors/fridgify-recipes.ts"],"names":[],"mappings":"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"}

package/dist/collectors/playstore.d.ts

@@ -0,0 +1,46 @@
+import type { StoreReview } from "../types/collectors.js";
+/**
+ * Google Play Developer API collector.
+ * Uses a Service Account JSON for authentication via JWT → OAuth token exchange.
+ *
+ * @see https://developers.google.com/android-publisher
+ */
+export interface PlayStoreServiceAccount {
+    client_email: string;
+    private_key: string;
+}
+export interface PlayStoreCollectorOptions {
+    serviceAccountJson: PlayStoreServiceAccount | string;
+}
+/**
+ * Test-only overrides. Kept off {@link PlayStoreCollectorOptions} so
+ * production config loaders cannot feed a user-controlled URL into the
+ * SSRF surface.
+ */
+export interface PlayStoreCollectorTestHooks {
+    baseUrl?: string;
+    tokenUrl?: string;
+}
+export declare class PlayStoreCollector {
+    private readonly serviceAccount;
+    private readonly baseUrl;
+    private readonly tokenUrl;
+    private accessToken;
+    private tokenExpiresAt;
+    constructor(options: PlayStoreCollectorOptions, testHooks?: PlayStoreCollectorTestHooks);
+    private getAccessToken;
+    private request;
+    /**
+     * Fetch reviews for a package.
+     */
+    getReviews(packageName: string): Promise<StoreReview[]>;
+    /**
+     * Fetch app listing details (title, short/full description) for a locale.
+     */
+    getAppDetails(packageName: string, locale?: string): Promise<unknown>;
+    /**
+     * Reply to a review on Google Play. Approval-gated write path.
+     */
+    replyToReview(packageName: string, reviewId: string, replyText: string): Promise<unknown>;
+}
+//# sourceMappingURL=playstore.d.ts.map

package/dist/collectors/playstore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playstore.d.ts","sourceRoot":"","sources":["../../src/collectors/playstore.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,yBAAyB;IACxC,kBAAkB,EAAE,uBAAuB,GAAG,MAAM,CAAC;CACtD;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA+BD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0B;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,cAAc,CAAK;gBAGzB,OAAO,EAAE,yBAAyB,EAClC,SAAS,CAAC,EAAE,2BAA2B;YA+B3B,cAAc;YAsCd,OAAO;IAmCrB;;OAEG;IACG,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IA0B7D;;OAEG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,SAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IAM5E;;OAEG;IACG,aAAa,CACjB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC;CAiBpB"}

package/dist/collectors/playstore.js

@@ -0,0 +1,140 @@
+import { SignJWT, importPKCS8 } from "jose";
+import { AuthError, ExternalApiError, RateLimitError } from "../utils/errors.js";
+import { parseRetryAfter } from "../utils/retry.js";
+const DEFAULT_BASE_URL = "https://androidpublisher.googleapis.com/androidpublisher/v3";
+const DEFAULT_TOKEN_URL = "https://oauth2.googleapis.com/token";
+const REPLY_LIMIT = 350;
+export class PlayStoreCollector {
+    serviceAccount;
+    baseUrl;
+    tokenUrl;
+    accessToken = null;
+    tokenExpiresAt = 0;
+    constructor(options, testHooks) {
+        if (!options.serviceAccountJson) {
+            throw new Error("PlayStoreCollector requires serviceAccountJson");
+        }
+        if (typeof options.serviceAccountJson === "string") {
+            try {
+                this.serviceAccount = JSON.parse(options.serviceAccountJson);
+            }
+            catch {
+                // Never surface parser errors verbatim — the raw text may contain
+                // a leading fragment of the private key.
+                throw new AuthError("PlayStoreCollector: serviceAccountJson is not valid JSON");
+            }
+        }
+        else {
+            this.serviceAccount = options.serviceAccountJson;
+        }
+        if (!this.serviceAccount.client_email || !this.serviceAccount.private_key) {
+            throw new Error("PlayStoreCollector: serviceAccountJson must include client_email and private_key");
+        }
+        this.baseUrl = testHooks?.baseUrl ?? DEFAULT_BASE_URL;
+        this.tokenUrl = testHooks?.tokenUrl ?? DEFAULT_TOKEN_URL;
+    }
+    async getAccessToken() {
+        if (this.accessToken && Date.now() < this.tokenExpiresAt) {
+            return this.accessToken;
+        }
+        const key = await importPKCS8(this.serviceAccount.private_key, "RS256");
+        const jwt = await new SignJWT({
+            scope: "https://www.googleapis.com/auth/androidpublisher",
+        })
+            .setProtectedHeader({ alg: "RS256", typ: "JWT" })
+            .setIssuer(this.serviceAccount.client_email)
+            .setAudience(this.tokenUrl)
+            .setIssuedAt()
+            .setExpirationTime("1h")
+            .sign(key);
+        const response = await fetch(this.tokenUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+                assertion: jwt,
+            }),
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new ExternalApiError(`Google OAuth failed: ${body}`, {
+                statusCode: response.status,
+            });
+        }
+        const data = (await response.json());
+        this.accessToken = data.access_token;
+        this.tokenExpiresAt = Date.now() + (data.expires_in - 60) * 1000;
+        return this.accessToken;
+    }
+    async request(path, init) {
+        const token = await this.getAccessToken();
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            Authorization: `Bearer ${token}`,
+            ...(init?.body !== undefined ? { "Content-Type": "application/json" } : {}),
+            ...(init?.headers ?? {}),
+        };
+        const fetchInit = { headers };
+        if (init?.method !== undefined)
+            fetchInit.method = init.method;
+        if (init?.body !== undefined)
+            fetchInit.body = init.body;
+        const response = await fetch(url, fetchInit);
+        if (response.status === 429) {
+            throw new RateLimitError("Google Play API rate limited", {
+                retryAfterSeconds: parseRetryAfter(response.headers.get("Retry-After")),
+            });
+        }
+        if (!response.ok) {
+            const body = await response.text();
+            throw new ExternalApiError(`Google Play API ${String(response.status)}: ${body}`, { statusCode: response.status });
+        }
+        return (await response.json());
+    }
+    /**
+     * Fetch reviews for a package.
+     */
+    async getReviews(packageName) {
+        const data = await this.request(`/applications/${packageName}/reviews`);
+        return (data.reviews ?? []).map((r) => {
+            const comment = r.comments?.[0]?.userComment;
+            const rawSeconds = comment?.lastModified?.seconds;
+            const seconds = typeof rawSeconds === "string"
+                ? Number.parseInt(rawSeconds, 10)
+                : typeof rawSeconds === "number"
+                    ? rawSeconds
+                    : null;
+            const createdAt = seconds !== null && Number.isFinite(seconds)
+                ? new Date(seconds * 1000).toISOString()
+                : null;
+            return {
+                reviewId: r.reviewId,
+                rating: comment?.starRating ?? 0,
+                body: comment?.text ?? "",
+                createdAt,
+            };
+        });
+    }
+    /**
+     * Fetch app listing details (title, short/full description) for a locale.
+     */
+    async getAppDetails(packageName, locale = "ko-KR") {
+        return this.request(`/applications/${packageName}/edits/-/listings/${locale}`);
+    }
+    /**
+     * Reply to a review on Google Play. Approval-gated write path.
+     */
+    async replyToReview(packageName, reviewId, replyText) {
+        if (typeof replyText !== "string" || replyText.trim().length === 0) {
+            throw new Error("replyToReview: replyText must be a non-empty string");
+        }
+        if (replyText.length > REPLY_LIMIT) {
+            throw new Error(`replyToReview: replyText exceeds Google Play ${String(REPLY_LIMIT)} char limit (${String(replyText.length)})`);
+        }
+        return this.request(`/applications/${packageName}/reviews/${reviewId}:reply`, {
+            method: "POST",
+            body: JSON.stringify({ replyText }),
+        });
+    }
+}
+//# sourceMappingURL=playstore.js.map

package/dist/collectors/playstore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playstore.js","sourceRoot":"","sources":["../../src/collectors/playstore.ts"],"names":[],"mappings":"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"}

package/dist/collectors/youtube.d.ts

@@ -0,0 +1,44 @@
+import type { YouTubeVideoStats } from "../types/collectors.js";
+/**
+ * YouTube Data API v3 client for collecting Shorts performance metrics.
+ *
+ * Used by `ShortFormSkill` (M5) to pull recent Shorts from a channel and
+ * fetch their view / like / comment counts so the weekly briefing can
+ * show week-over-week changes.
+ *
+ * @see https://developers.google.com/youtube/v3
+ */
+export interface YouTubeCollectorOptions {
+    apiKey: string;
+}
+/**
+ * Test-only overrides. `baseUrl` is intentionally kept off
+ * {@link YouTubeCollectorOptions} so production config loaders cannot
+ * override Google's API host; the allowlist still gates any test-hook
+ * value as defense-in-depth.
+ */
+export interface YouTubeCollectorTestHooks {
+    baseUrl?: string;
+}
+export declare class YouTubeCollector {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(options: YouTubeCollectorOptions, testHooks?: YouTubeCollectorTestHooks);
+    private redact;
+    private fetchJson;
+    /**
+     * Get recent Shorts videos from a channel.
+     *
+     * YouTube's `videoDuration=short` search filter returns clips under
+     * **4 minutes** (not 60 seconds). We cross-check the content-details
+     * duration against `maxDurationSeconds` (default 60) so callers get a
+     * correct "Shorts" bucket by default. Pass a larger value (e.g. 180)
+     * if you want YouTube's looser "short-form" definition.
+     */
+    getRecentShorts(channelId: string, maxResults?: number, maxDurationSeconds?: number): Promise<YouTubeVideoStats[]>;
+    /**
+     * Get statistics for specific video IDs.
+     */
+    getVideoStats(videoIds: string[]): Promise<YouTubeVideoStats[]>;
+}
+//# sourceMappingURL=youtube.d.ts.map

package/dist/collectors/youtube.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"youtube.d.ts","sourceRoot":"","sources":["../../src/collectors/youtube.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAKD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAG/B,OAAO,EAAE,uBAAuB,EAChC,SAAS,CAAC,EAAE,yBAAyB;IASvC,OAAO,CAAC,MAAM;YAIA,SAAS;IAgCvB;;;;;;;;OAQG;IACG,eAAe,CACnB,SAAS,EAAE,MAAM,EACjB,UAAU,SAAK,EACf,kBAAkB,SAAK,GACtB,OAAO,CAAC,iBAAiB,EAAE,CAAC;IA2B/B;;OAEG;IACG,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;CAkCtE"}