@appeeky/spec 0.0.0-stage → 0.2.0

package/dist/setup.js

@@ -0,0 +1,259 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { installedTargets } from "./agents.js";
+import { SPEC_DIR, SPEC_FILE } from "./files.js";
+import { normalize, words } from "./text.js";
+import { STORE_CLIS, onPath } from "./transport.js";
+/** App Store apps matching a name, from Apple's public search. */
+export async function findApps(term, country = "us", fetcher = fetch) {
+    const url = `https://itunes.apple.com/search?media=software&entity=software&limit=6&country=${encodeURIComponent(country)}&term=${encodeURIComponent(term)}`;
+    const res = await fetcher(url, { headers: { "User-Agent": "appeeky-spec" } });
+    if (!res.ok)
+        return [];
+    const json = (await res.json());
+    return (json.results ?? [])
+        .filter((r) => r.trackId && r.trackName)
+        .map((r) => ({
+        id: String(r.trackId),
+        name: r.trackName,
+        developer: r.sellerName ?? r.artistName ?? "",
+        bundleId: r.bundleId ?? "",
+        ...(r.averageUserRating ? { rating: Math.round(r.averageUserRating * 10) / 10 } : {}),
+    }));
+}
+/** Whether a Google Play package has a public store page. */
+export async function playPackageExists(pkg, fetcher = fetch) {
+    try {
+        const res = await fetcher(`https://play.google.com/store/apps/details?id=${encodeURIComponent(pkg)}&hl=en`, { method: "HEAD", headers: { "User-Agent": "Mozilla/5.0 appeeky-spec" } });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Targets ─────────────────────────────────────────────────────────────────
+/** Words nobody searches with, at the start or the end of a phrase ("AI-powered", "the best"). */
+const FILLER = new Set("a an the and or for with your my our to of in on by best top new free app apps powered based simple easy fast smart ultimate official".split(" "));
+/**
+ * Searches the listing already speaks to: the parts of the name and subtitle between
+ * punctuation ("Sleep Sounds: Rain & Ocean" → "sleep sounds", "rain", "ocean"), their two-word
+ * runs, and keyword-field entries. The brand (the name's first part, alone) is left out.
+ */
+export function targetCandidates(project, limit = 14, storeName) {
+    const locale = project.spec.app.primaryLocale;
+    const asc = project.listings["app-store"][locale];
+    const play = project.listings["google-play"][locale] ?? Object.values(project.listings["google-play"])[0];
+    const name = asc?.name ?? play?.title ?? storeName ?? project.spec.app.name;
+    const subtitle = asc?.subtitle ?? play?.shortDescription ?? "";
+    const brand = normalize(project.spec.app.name).trim();
+    const out = [];
+    const add = (phrase) => {
+        const ws = words(phrase);
+        const p = ws.join(" ");
+        if (!p || p.length < 3 || p === brand || out.includes(p) || ws.length > 3)
+            return;
+        if (FILLER.has(ws[0]) || FILLER.has(ws[ws.length - 1]))
+            return;
+        out.push(p);
+    };
+    for (const text of [name, subtitle]) {
+        for (const part of text.split(/[:\-–—|,&+/()]| and | for | with /i)) {
+            add(part);
+            const ws = words(part);
+            for (let i = 0; i + 1 < ws.length; i++)
+                add(`${ws[i]} ${ws[i + 1]}`);
+        }
+    }
+    for (const k of (asc?.keywords ?? "").split(","))
+        add(k);
+    return out.slice(0, limit);
+}
+/**
+ * The searches to start with: the ones the app already ranks for (a target you are near is
+ * the cheapest win), best first, then two-word phrases from the listing.
+ */
+export async function suggestTargets(candidates, appId, country, source, count = 5) {
+    const ranks = appId ? await source.ranks("app-store", appId, country, candidates).catch(() => ({})) : {};
+    const ranked = candidates.map((keyword) => ({ keyword, rank: ranks[keyword] ?? null }));
+    const found = ranked.filter((r) => r.rank !== null).sort((a, b) => a.rank - b.rank);
+    const rest = ranked.filter((r) => r.rank === null).sort((a, b) => b.keyword.split(" ").length - a.keyword.split(" ").length);
+    return [...found, ...rest].slice(0, count);
+}
+// ── GitHub workflows ────────────────────────────────────────────────────────
+export const WORKFLOWS = {
+    "listing-check.yml": `# Appeeky Spec: report listing changes on every pull request.
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write     # to comment
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0     # the report compares with main
+      - uses: appeeky/appeeky-spec@v0
+`,
+    "listing-push.yml": `# Appeeky Spec: push the listing to the stores when a change is merged, and send the
+# social posts and make the UGC clips a merged pull request approved.
+on:
+  push:
+    branches: [main]
+    paths: ["appeeky/store/**", "appeeky.spec.yaml", "appeeky/social/drafts/**", "appeeky/ugc/briefs/**"]
+permissions:
+  contents: write          # to commit the release file
+jobs:
+  push:
+    runs-on: ubuntu-latest
+    environment: stores    # optional: a required approval before it runs
+    steps:
+      - uses: actions/checkout@v4
+      - run: |
+          npx @appeeky/spec push --yes --note "\${{ github.event.head_commit.message }}"
+          npx @appeeky/spec social push --yes
+          npx @appeeky/spec ugc generate --yes \${FAL_KEY:+--local}
+        env:
+          APPEEKY_API_KEY: \${{ secrets.APPEEKY_API_KEY }}
+          FAL_KEY: \${{ secrets.FAL_KEY }}    # optional: render clips on your own fal account
+      - uses: actions/upload-artifact@v4      # clips made with FAL_KEY, kept with the run
+        if: hashFiles('.appeeky/media/*.mp4') != ''
+        with: { name: ugc-clips, path: .appeeky/media/*.mp4 }
+      - run: |
+          git config user.name "appeeky-spec"
+          git config user.email "spec@users.noreply.github.com"
+          git add appeeky && git commit -m "Record release, posts and clips" && git push || true
+`,
+    "listing-daily.yml": `# Appeeky Spec: record the category rank, AI visibility and Google search, measure releases on day 7 and 14, refresh reviews and competitors.
+on:
+  schedule: [{ cron: "0 6 * * *" }]   # 06:00 UTC
+  workflow_dispatch:
+permissions:
+  contents: write
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: |
+          npx @appeeky/spec category pull || true
+          npx @appeeky/spec visibility pull || true
+          npx @appeeky/spec verify --playbook
+          npx @appeeky/spec reviews pull || true
+          npx @appeeky/spec competitors pull || true
+          npx @appeeky/spec social pull || true
+          npx @appeeky/spec ugc pull || true
+          # Your own keys: Search Console with a service account, Apple Search Ads with an API user, Google ranks on
+          # DataForSEO every SEO_RANKS_EVERY days (default 7), and AI visibility every N days
+          # (set the repository variable VISIBILITY_EVERY, e.g. 7) on OpenAI, Anthropic, Gemini or Perplexity.
+          if [ -n "$GSC_CREDENTIALS" ]; then npx @appeeky/spec seo pull || true; fi
+          if [ -n "$ASA_CLIENT_ID" ]; then npx @appeeky/spec search-ads pull || true; fi
+          if [ -n "$DATAFORSEO_LOGIN" ]; then npx @appeeky/spec seo ranks --every "\${SEO_RANKS_EVERY:-7}" --yes || true; fi
+          if [ -n "$VISIBILITY_EVERY" ]; then npx @appeeky/spec visibility scan --local --every "$VISIBILITY_EVERY" --yes || true; fi
+        env:
+          APPEEKY_API_KEY: \${{ secrets.APPEEKY_API_KEY }}
+          GSC_CREDENTIALS: \${{ secrets.GSC_CREDENTIALS }}
+          ASA_CLIENT_ID: \${{ secrets.ASA_CLIENT_ID }}
+          ASA_TEAM_ID: \${{ secrets.ASA_TEAM_ID }}
+          ASA_KEY_ID: \${{ secrets.ASA_KEY_ID }}
+          ASA_PRIVATE_KEY: \${{ secrets.ASA_PRIVATE_KEY }}
+          DATAFORSEO_LOGIN: \${{ secrets.DATAFORSEO_LOGIN }}
+          DATAFORSEO_PASSWORD: \${{ secrets.DATAFORSEO_PASSWORD }}
+          SEO_RANKS_EVERY: \${{ vars.SEO_RANKS_EVERY }}
+          VISIBILITY_EVERY: \${{ vars.VISIBILITY_EVERY }}
+          OPENAI_API_KEY: \${{ secrets.OPENAI_API_KEY }}
+          ANTHROPIC_API_KEY: \${{ secrets.ANTHROPIC_API_KEY }}
+          GEMINI_API_KEY: \${{ secrets.GEMINI_API_KEY }}
+          PERPLEXITY_API_KEY: \${{ secrets.PERPLEXITY_API_KEY }}
+      - run: |
+          git config user.name "appeeky-spec"
+          git config user.email "spec@users.noreply.github.com"
+          git add appeeky && git commit -m "Daily: category, AI visibility, search, Search Ads, verify, reviews, competitors, social, UGC" && git push || true
+`,
+};
+const ok = (area, detail) => ({ area, status: "ok", detail });
+const warn = (area, detail, fix) => ({ area, status: "warn", detail, fix });
+const fail = (area, detail, fix) => ({ area, status: "fail", detail, fix });
+const hasLocalKeys = (store, env) => store === "app-store"
+    ? Boolean(env.ASC_KEY_ID && (env.ASC_PRIVATE_KEY || env.ASC_PRIVATE_KEY_PATH))
+    : Boolean(env.GPS_CREDENTIALS || env.GOOGLE_PLAY_CREDENTIALS || env.GOOGLE_APPLICATION_CREDENTIALS);
+/** Where each store CLI keeps its saved accounts (`appstore accounts add`, `gps accounts add`). */
+export function savedAccountsFile(store, env = process.env) {
+    const base = env.XDG_CONFIG_HOME ?? join(env.HOME ?? env.USERPROFILE ?? "", ".config");
+    return join(base, store === "app-store" ? "appstore" : "gps", "config.json");
+}
+/** Names of the accounts saved with the store CLI, if any. */
+export function savedAccounts(store, env = process.env) {
+    try {
+        const config = JSON.parse(readFileSync(savedAccountsFile(store, env), "utf8"));
+        const accounts = config.accounts;
+        return Array.isArray(accounts) ? accounts.map((a) => String(a.name ?? a)) : Object.keys(accounts ?? {});
+    }
+    catch {
+        return [];
+    }
+}
+/** What is set up for this repo, and what is missing. Works without a spec (it says so). */
+export function diagnose(root, project, env = process.env, nodeVersion = process.versions.node) {
+    const out = [];
+    const major = Number(nodeVersion.split(".")[0]);
+    out.push(major >= 20 ? ok("node", `Node ${nodeVersion}`) : fail("node", `Node ${nodeVersion}`, "Install Node 20 or newer."));
+    if (!project) {
+        out.push(fail("spec", `No ${SPEC_FILE} here or above`, "Run `npx @appeeky/spec init` in your app's repo."));
+        return out;
+    }
+    out.push(ok("spec", `${SPEC_FILE} · ${project.spec.app.name}`));
+    const key = Boolean(env.APPEEKY_API_KEY);
+    const stores = [...(project.spec.stores.appStore ? ["app-store"] : []), ...(project.spec.stores.googlePlay ? ["google-play"] : [])];
+    if (stores.length === 0)
+        out.push(fail("stores", "No store in the spec", "Add stores.appStore.appId or stores.googlePlay.packageName, or run `init` again."));
+    for (const store of stores) {
+        const cli = STORE_CLIS[store];
+        const label = store === "app-store" ? "App Store" : "Google Play";
+        const via = (store === "app-store" ? project.spec.stores.appStore?.via : project.spec.stores.googlePlay?.via) ?? "auto";
+        const local = onPath(cli.bin, env);
+        // The CLI runs from PATH or through npx; either way it reads keys from the environment or its saved accounts.
+        const accounts = savedAccounts(store, env);
+        const keys = hasLocalKeys(store, env) ? "keys in the environment" : accounts.length ? `saved account${accounts.length > 1 ? "s" : ""} ${accounts.join(", ")}` : "";
+        const runner = local ? `${cli.bin} CLI` : `npx ${cli.npmPackage}`;
+        if (via === "hosted")
+            out.push(key ? ok(label, "hosted through your Appeeky connection (APPEEKY_API_KEY)") : fail(label, "via: hosted, but APPEEKY_API_KEY is not set", "Set APPEEKY_API_KEY (appeeky.com/dashboard/settings)."));
+        else if (keys && (via === "local" || local || !key))
+            out.push(ok(label, `your own key: ${runner}, ${keys}`));
+        else if (via !== "local" && key)
+            out.push(ok(label, "hosted through your Appeeky connection (APPEEKY_API_KEY)"));
+        else if (local)
+            out.push(fail(label, `${cli.bin} CLI is installed but has no saved account and no keys in the environment`, cli.setupHint));
+        else
+            out.push(fail(label, `No store key saved, no ${cli.bin} CLI and no APPEEKY_API_KEY`, cli.setupHint));
+        const files = Object.keys(project.listings[store]).length;
+        out.push(files ? ok(`${label} listing`, `${files} locale${files === 1 ? "" : "s"} in ${SPEC_DIR}/store/${store}/`) : warn(`${label} listing`, "Not pulled yet", `Run \`npx @appeeky/spec pull --store ${store}\`.`));
+    }
+    const targets = Object.entries(project.spec.targets).filter(([, list]) => list.length > 0);
+    const count = targets.reduce((n, [, list]) => n + list.length, 0);
+    out.push(count ? ok("targets", `${count} in ${targets.map(([cc]) => cc).join(", ")}`) : fail("targets", "None yet: coverage and verify have nothing to measure", "Add the searches to win under targets:, or run `npx @appeeky/spec suggest`."));
+    if (targets.length === 1)
+        out.push(warn("control group", "Targets in one storefront only", "Add a few targets for a second country: verify compares the storefronts a release changed with the ones it did not."));
+    out.push(key ? ok("Appeeky API", "APPEEKY_API_KEY set: popularity, both stores' ranks, conversion, revenue, ads") : warn("Appeeky API", "Not set: App Store ranks only, no popularity or outcome metrics", "Optional: set APPEEKY_API_KEY."));
+    const attribution = project.spec.attribution;
+    if (!attribution)
+        out.push(warn("attribution", "Not set up: releases are judged on ranks and store numbers", "Optional: `npx @appeeky/spec attribution init`."));
+    else if (attribution.via === "self" && !env.ATTRIBUTION_TOKEN)
+        out.push(fail("attribution", "via: self, but ATTRIBUTION_TOKEN is not set", "Set ATTRIBUTION_TOKEN to your server's ADMIN_TOKEN."));
+    else if (attribution.via === "hosted" && !key)
+        out.push(fail("attribution", "via: hosted, but APPEEKY_API_KEY is not set", "Set APPEEKY_API_KEY."));
+    else
+        out.push(ok("attribution", `${attribution.via === "self" ? attribution.url : "Appeeky hosted"}`));
+    const workflows = join(root, ".github", "workflows");
+    const found = existsSync(workflows) ? readdirSync(workflows).filter((f) => /\.ya?ml$/.test(f) && /appeeky\/appeeky-spec|@appeeky\/spec/.test(readFileSync(join(workflows, f), "utf8"))) : [];
+    out.push(found.length ? ok("GitHub Actions", found.join(", ")) : warn("GitHub Actions", "No workflow runs the spec", "Optional: `npx @appeeky/spec init --ci` writes the pull request check, push on merge and daily verify."));
+    const skills = [".claude/skills/appeeky-spec", ".agents/skills/appeeky-spec", ".cursor/skills/appeeky-spec"].some((p) => existsSync(join(root, p)));
+    out.push(skills ? ok("agent skills", "installed") : warn("agent skills", "Not installed in this repo", "Optional: `npx skills add appeeky/appeeky-spec`."));
+    const specialists = installedTargets(root);
+    out.push(specialists.length ? ok("specialist agents", `installed for ${specialists.join(", ")}`) : warn("specialist agents", "Not installed: no co-founder review in this repo", "Optional: `npx @appeeky/spec agents install` (add --for opencode or all)."));
+    const ignore = existsSync(join(root, ".gitignore")) ? readFileSync(join(root, ".gitignore"), "utf8") : "";
+    if (!/\.appeeky\/?(\s|$)|\.appeeky\/data|\.appeeky\/\*/m.test(ignore))
+        out.push(warn(".gitignore", ".appeeky/ is not ignored: data and cache could be committed", "Add `.appeeky/` to .gitignore."));
+    return out;
+}
+//# sourceMappingURL=setup.js.map

package/dist/social.d.ts

@@ -0,0 +1,129 @@
+import { z } from "zod";
+import type { AppeekyApi } from "./appeeky-api.js";
+/**
+ * Organic social media in the repo, through the accounts connected in Appeeky (APPEEKY_API_KEY,
+ * Startup plan or above):
+ *
+ *   appeeky/social/accounts.yaml        the connected accounts (platform, name, id)
+ *   appeeky/social/posts.jsonl          recent posts, one per line, with each platform's result
+ *   appeeky/social/summary.md           the last 30 days per platform, and the posts that did best
+ *   appeeky/social/drafts/<name>.yaml   a post: drafted, reviewed in a pull request, then sent
+ *
+ * Sending creates the post in Appeeky, which publishes it right away, or at `when`.
+ */
+export declare const METRICS: readonly ["views", "impressions", "reach", "likes", "comments", "shares", "reposts", "saves", "clicks"];
+export type SocialMetric = (typeof METRICS)[number];
+export interface SocialAccount {
+    id: string;
+    platform: string;
+    name: string;
+    active: boolean;
+}
+export interface SocialPlatformResult {
+    platform: string;
+    status: string;
+    url?: string;
+    publishedAt?: string;
+    error?: string;
+    metrics?: Partial<Record<SocialMetric, number>>;
+}
+export interface SocialPost {
+    id: string;
+    status: string;
+    text: string;
+    createdAt: string;
+    scheduledFor?: string;
+    platforms: SocialPlatformResult[];
+}
+export declare const socialDir: (root: string) => string;
+export declare const draftsDir: (root: string) => string;
+interface AccountRow {
+    id: string;
+    platform: string;
+    displayName?: string | null;
+    platformUserId?: string | null;
+    isActive?: boolean | null;
+    needsReconnect?: boolean | null;
+}
+interface PostRow {
+    id: string;
+    content: string;
+    status: string;
+    created_at: string;
+    scheduled_for: string | null;
+    social_media_platform_posts?: Array<{
+        platform: string;
+        status: string;
+        platform_post_url: string | null;
+        published_at: string | null;
+        error_message: string | null;
+    }>;
+}
+interface AnalyticsItem {
+    platform: string;
+    analytics: Record<string, unknown>;
+}
+export declare function toAccount(r: AccountRow): SocialAccount;
+export declare function toPost(r: PostRow, analytics?: AnalyticsItem[]): SocialPost;
+/** Connected accounts and the latest posts, with analytics for the ones that went out. */
+export declare function fetchSocial(api: AppeekyApi, options?: {
+    limit?: number;
+}): Promise<{
+    accounts: SocialAccount[];
+    posts: SocialPost[];
+}>;
+export declare function summaryMarkdown(accounts: SocialAccount[], posts: SocialPost[], now?: Date): string;
+export declare function saveSocial(root: string, data: {
+    accounts: SocialAccount[];
+    posts: SocialPost[];
+}, now?: Date): Promise<void>;
+export declare function readAccounts(root: string): Promise<SocialAccount[]>;
+export declare const draftSchema: z.ZodObject<{
+    /** Platforms (twitter, instagram, tiktok, …) or account ids from accounts.yaml. */
+    accounts: z.ZodArray<z.ZodString, "many">;
+    text: z.ZodString;
+    /** ISO time to schedule it; without it, the post goes out when it is sent. */
+    when: z.ZodOptional<z.ZodString>;
+    /** Public image or video URLs. Instagram, TikTok and Pinterest need one. */
+    media: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Why this post, for whoever reviews the pull request. */
+    why: z.ZodOptional<z.ZodString>;
+    status: z.ZodDefault<z.ZodEnum<["draft", "sent"]>>;
+    postId: z.ZodOptional<z.ZodString>;
+    sentAt: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    status: "draft" | "sent";
+    accounts: string[];
+    text: string;
+    when?: string | undefined;
+    media?: string[] | undefined;
+    why?: string | undefined;
+    postId?: string | undefined;
+    sentAt?: string | undefined;
+}, {
+    accounts: string[];
+    text: string;
+    status?: "draft" | "sent" | undefined;
+    when?: string | undefined;
+    media?: string[] | undefined;
+    why?: string | undefined;
+    postId?: string | undefined;
+    sentAt?: string | undefined;
+}>;
+export type Draft = z.infer<typeof draftSchema>;
+/** Character limits per platform, for `check`-style warnings before sending. */
+export declare const TEXT_LIMIT: Record<string, number>;
+export declare function readDrafts(root: string): Promise<Array<Draft & {
+    file: string;
+}>>;
+/** The connected accounts a draft goes to: platform names match every active account on that platform. */
+export declare function resolveAccounts(draft: Draft, accounts: SocialAccount[]): {
+    accounts: SocialAccount[];
+    missing: string[];
+};
+export declare function draftIssues(draft: Draft, accounts: SocialAccount[], now?: Date): string[];
+/** Create the post in Appeeky (it publishes now, or at `when`) and mark the draft sent. */
+export declare function sendDraft(api: AppeekyApi, draft: Draft & {
+    file: string;
+}, accounts: SocialAccount[], now?: Date): Promise<string>;
+export {};

package/dist/social.js

@@ -0,0 +1,189 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import YAML from "yaml";
+import { z } from "zod";
+import { SPEC_DIR, SpecError } from "./files.js";
+/**
+ * Organic social media in the repo, through the accounts connected in Appeeky (APPEEKY_API_KEY,
+ * Startup plan or above):
+ *
+ *   appeeky/social/accounts.yaml        the connected accounts (platform, name, id)
+ *   appeeky/social/posts.jsonl          recent posts, one per line, with each platform's result
+ *   appeeky/social/summary.md           the last 30 days per platform, and the posts that did best
+ *   appeeky/social/drafts/<name>.yaml   a post: drafted, reviewed in a pull request, then sent
+ *
+ * Sending creates the post in Appeeky, which publishes it right away, or at `when`.
+ */
+export const METRICS = ["views", "impressions", "reach", "likes", "comments", "shares", "reposts", "saves", "clicks"];
+export const socialDir = (root) => join(root, SPEC_DIR, "social");
+export const draftsDir = (root) => join(socialDir(root), "drafts");
+const compact = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined && v !== null && v !== ""));
+export function toAccount(r) {
+    return { id: r.id, platform: r.platform, name: r.displayName || r.platformUserId || r.platform, active: r.isActive !== false && !r.needsReconnect };
+}
+export function toPost(r, analytics = []) {
+    return compact({
+        id: r.id,
+        status: r.status,
+        text: r.content,
+        createdAt: r.created_at,
+        scheduledFor: r.scheduled_for ?? undefined,
+        platforms: (r.social_media_platform_posts ?? []).map((p) => {
+            const a = analytics.find((x) => x.platform === p.platform)?.analytics ?? {};
+            const metrics = Object.fromEntries(METRICS.filter((k) => typeof a[k] === "number" && a[k] > 0).map((k) => [k, a[k]]));
+            return compact({
+                platform: p.platform,
+                status: p.status,
+                url: p.platform_post_url ?? undefined,
+                publishedAt: p.published_at ?? undefined,
+                error: p.error_message ?? undefined,
+                metrics: Object.keys(metrics).length ? metrics : undefined,
+            });
+        }),
+    });
+}
+/** Connected accounts and the latest posts, with analytics for the ones that went out. */
+export async function fetchSocial(api, options = {}) {
+    const accounts = ((await api.get("/connect/social/accounts")) ?? []).map(toAccount);
+    const rows = (await api.get("/social/posts", { limit: String(options.limit ?? 100) })) ?? [];
+    const posts = [];
+    for (const row of rows) {
+        const published = (row.social_media_platform_posts ?? []).some((p) => p.published_at);
+        const analytics = published ? ((await api.get(`/social/posts/${encodeURIComponent(row.id)}/analytics`).catch(() => null))?.analytics ?? []) : [];
+        posts.push(toPost(row, analytics));
+    }
+    return { accounts, posts };
+}
+const total = (p, k) => p.metrics?.[k] ?? 0;
+/** The reach of a post on one platform: views when the platform reports them, else impressions or reach. */
+const seen = (p) => total(p, "views") || total(p, "impressions") || total(p, "reach");
+export function summaryMarkdown(accounts, posts, now = new Date()) {
+    const since = new Date(now.getTime() - 30 * 86_400_000).toISOString();
+    const recent = posts.filter((p) => (p.platforms.find((x) => x.publishedAt)?.publishedAt ?? p.createdAt) >= since);
+    const lines = [`# Social media`, "", `Updated ${now.toISOString().slice(0, 10)}. The last 30 days, from the accounts connected in Appeeky.`, ""];
+    lines.push("## Accounts", "");
+    if (!accounts.length)
+        lines.push("None connected. Connect them in Appeeky (Social).");
+    for (const a of accounts)
+        lines.push(`- ${a.platform}: ${a.name}${a.active ? "" : " (needs reconnecting in Appeeky)"}`);
+    lines.push("", "## By platform", "");
+    const platforms = [...new Set(recent.flatMap((p) => p.platforms.map((x) => x.platform)))].sort();
+    if (!platforms.length)
+        lines.push("No posts in the last 30 days.");
+    else {
+        lines.push("| Platform | Posts | Seen | Likes | Comments | Shares | Failed |", "| --- | --- | --- | --- | --- | --- | --- |");
+        for (const platform of platforms) {
+            const results = recent.flatMap((p) => p.platforms.filter((x) => x.platform === platform));
+            const sum = (f) => results.reduce((n, x) => n + f(x), 0);
+            lines.push(`| ${platform} | ${results.filter((x) => x.publishedAt).length} | ${sum(seen)} | ${sum((x) => total(x, "likes"))} | ${sum((x) => total(x, "comments"))} | ${sum((x) => total(x, "shares") + total(x, "reposts"))} | ${results.filter((x) => x.error).length} |`);
+        }
+    }
+    const best = recent
+        .flatMap((p) => p.platforms.filter((x) => x.publishedAt).map((x) => ({ post: p, result: x })))
+        .sort((a, b) => seen(b.result) + total(b.result, "likes") * 10 - (seen(a.result) + total(a.result, "likes") * 10))
+        .slice(0, 5);
+    if (best.length) {
+        lines.push("", "## Did best", "");
+        for (const { post, result } of best) {
+            const text = post.text.replace(/\s+/g, " ").slice(0, 90);
+            lines.push(`- ${result.platform}, ${result.publishedAt.slice(0, 10)}: ${seen(result)} seen, ${total(result, "likes")} likes. "${text}${post.text.length > 90 ? "…" : ""}"${result.url ? ` ${result.url}` : ""}`);
+        }
+    }
+    const waiting = posts.filter((p) => p.status === "scheduled" || p.status === "pending");
+    if (waiting.length) {
+        lines.push("", "## Waiting to go out", "");
+        for (const p of waiting)
+            lines.push(`- ${p.scheduledFor?.slice(0, 16).replace("T", " ") ?? "now"} on ${p.platforms.map((x) => x.platform).join(", ")}: "${p.text.replace(/\s+/g, " ").slice(0, 80)}"`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+export async function saveSocial(root, data, now = new Date()) {
+    await mkdir(socialDir(root), { recursive: true });
+    await writeFile(join(socialDir(root), "accounts.yaml"), YAML.stringify({ accounts: data.accounts }, { lineWidth: 0 }));
+    await writeFile(join(socialDir(root), "posts.jsonl"), data.posts.map((p) => JSON.stringify(p)).join("\n") + (data.posts.length ? "\n" : ""));
+    await writeFile(join(socialDir(root), "summary.md"), summaryMarkdown(data.accounts, data.posts, now));
+}
+export async function readAccounts(root) {
+    const file = join(socialDir(root), "accounts.yaml");
+    if (!existsSync(file))
+        return [];
+    return (YAML.parse(await readFile(file, "utf8"))?.accounts ?? []);
+}
+// ── Drafts ──────────────────────────────────────────────────────────────────
+export const draftSchema = z
+    .object({
+    /** Platforms (twitter, instagram, tiktok, …) or account ids from accounts.yaml. */
+    accounts: z.array(z.string().min(1)).min(1),
+    text: z.string().min(1),
+    /** ISO time to schedule it; without it, the post goes out when it is sent. */
+    when: z.string().optional(),
+    /** Public image or video URLs. Instagram, TikTok and Pinterest need one. */
+    media: z.array(z.string().url()).optional(),
+    /** Why this post, for whoever reviews the pull request. */
+    why: z.string().optional(),
+    status: z.enum(["draft", "sent"]).default("draft"),
+    postId: z.string().optional(),
+    sentAt: z.string().optional(),
+})
+    .strict();
+/** Character limits per platform, for `check`-style warnings before sending. */
+export const TEXT_LIMIT = { twitter: 280, x: 280, threads: 500, bluesky: 300, linkedin: 3000, instagram: 2200, tiktok: 2200, facebook: 63206, pinterest: 500, reddit: 40000 };
+const NEEDS_MEDIA = new Set(["instagram", "tiktok", "pinterest"]);
+export async function readDrafts(root) {
+    const dir = draftsDir(root);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of (await readdir(dir)).filter((f) => f.endsWith(".yaml")).sort()) {
+        const parsed = draftSchema.safeParse(YAML.parse(await readFile(join(dir, f), "utf8")));
+        if (!parsed.success)
+            throw new SpecError(parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "), join(dir, f));
+        out.push({ ...parsed.data, file: join(dir, f) });
+    }
+    return out;
+}
+/** The connected accounts a draft goes to: platform names match every active account on that platform. */
+export function resolveAccounts(draft, accounts) {
+    const found = [];
+    const missing = [];
+    for (const ref of draft.accounts) {
+        const key = ref.toLowerCase() === "x" ? "twitter" : ref.toLowerCase();
+        const match = accounts.filter((a) => a.active && (a.id === ref || a.platform.toLowerCase() === key));
+        if (match.length)
+            found.push(...match.filter((a) => !found.includes(a)));
+        else
+            missing.push(ref);
+    }
+    return { accounts: found, missing };
+}
+export function draftIssues(draft, accounts, now = new Date()) {
+    const issues = [];
+    const { accounts: to, missing } = resolveAccounts(draft, accounts);
+    if (missing.length)
+        issues.push(`no connected account for ${missing.join(", ")}`);
+    for (const a of to) {
+        const limit = TEXT_LIMIT[a.platform.toLowerCase()];
+        if (limit && draft.text.length > limit)
+            issues.push(`${a.platform}: ${draft.text.length}/${limit} characters`);
+        if (NEEDS_MEDIA.has(a.platform.toLowerCase()) && !draft.media?.length)
+            issues.push(`${a.platform} needs an image or video (media:)`);
+    }
+    if (draft.when && !(new Date(draft.when) > now))
+        issues.push(`when ${draft.when} is not in the future`);
+    return issues;
+}
+/** Create the post in Appeeky (it publishes now, or at `when`) and mark the draft sent. */
+export async function sendDraft(api, draft, accounts, now = new Date()) {
+    const { accounts: to } = resolveAccounts(draft, accounts);
+    const created = await api.post("/social/posts", {
+        content: draft.text,
+        account_ids: to.map((a) => a.id),
+        ...(draft.when ? { scheduled_for: new Date(draft.when).toISOString() } : {}),
+        ...(draft.media?.length ? { media_urls: draft.media } : {}),
+    });
+    const { file, ...rest } = draft;
+    await writeFile(file, YAML.stringify({ ...rest, status: "sent", postId: created.id, sentAt: now.toISOString() }, { lineWidth: 0 }));
+    return created.id;
+}
+//# sourceMappingURL=social.js.map

package/dist/storefronts.d.ts

@@ -0,0 +1,15 @@
+import type { Project } from "./schema.js";
+/**
+ * Listing locales each App Store storefront is commonly observed to index, in
+ * order of preference. Apple does not publish this list and it changes, so it
+ * is a starting point: override any storefront with `storefronts:` in
+ * `appeeky.spec.yaml`. Storefronts not listed here fall back to the app's
+ * primary locale.
+ */
+export declare const DEFAULT_STOREFRONT_LOCALES: Record<string, string[]>;
+/** Listing locales that count for a storefront, limited to locales the spec has. */
+export declare function indexedLocales(project: Project, country: string): string[];
+/** Best Google Play language for a storefront: exact match first, then the bare language, then the primary locale. */
+export declare function playLanguageFor(project: Project, country: string): string | undefined;
+/** The Google Play language for an App Store locale (`tr` → `tr-TR`, `zh-Hans` → `zh-CN`). */
+export declare function playLanguageCode(appStoreLocale: string): string;