@appeeky/spec 0.0.0-stage → 0.1.0

package/dist/storefronts.js

@@ -0,0 +1,89 @@
+/**
+ * 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 const DEFAULT_STOREFRONT_LOCALES = {
+    us: ["en-US", "es-MX"],
+    gb: ["en-GB"],
+    ca: ["en-CA", "fr-CA"],
+    au: ["en-AU"],
+    nz: ["en-AU", "en-GB"],
+    ie: ["en-GB"],
+    in: ["en-GB", "hi"],
+    de: ["de-DE"],
+    at: ["de-DE"],
+    ch: ["de-DE", "fr-FR", "it"],
+    fr: ["fr-FR"],
+    be: ["fr-FR", "nl-NL"],
+    nl: ["nl-NL"],
+    es: ["es-ES"],
+    mx: ["es-MX"],
+    ar: ["es-MX"],
+    co: ["es-MX"],
+    cl: ["es-MX"],
+    it: ["it"],
+    pt: ["pt-PT"],
+    br: ["pt-BR"],
+    tr: ["tr"],
+    ru: ["ru"],
+    ua: ["uk"],
+    pl: ["pl"],
+    se: ["sv"],
+    no: ["no"],
+    dk: ["da"],
+    fi: ["fi"],
+    cz: ["cs"],
+    gr: ["el"],
+    hu: ["hu"],
+    ro: ["ro"],
+    jp: ["ja"],
+    kr: ["ko"],
+    cn: ["zh-Hans"],
+    tw: ["zh-Hant"],
+    hk: ["zh-Hant"],
+    th: ["th"],
+    vn: ["vi"],
+    id: ["id"],
+    my: ["ms"],
+    sa: ["ar-SA"],
+    ae: ["ar-SA", "en-GB"],
+    il: ["he"],
+};
+/** Listing locales that count for a storefront, limited to locales the spec has. */
+export function indexedLocales(project, country) {
+    const cc = country.toLowerCase();
+    const available = Object.keys(project.listings["app-store"]);
+    const wanted = project.spec.storefronts[cc] ?? DEFAULT_STOREFRONT_LOCALES[cc] ?? [];
+    const present = wanted.filter((l) => available.includes(l));
+    if (present.length > 0)
+        return present;
+    const primary = project.spec.app.primaryLocale;
+    return available.includes(primary) ? [primary] : available.slice(0, 1);
+}
+/** Best Google Play language for a storefront: exact match first, then the bare language, then the primary locale. */
+export function playLanguageFor(project, country) {
+    const available = Object.keys(project.listings["google-play"]);
+    const appStoreGuess = (project.spec.storefronts[country] ?? DEFAULT_STOREFRONT_LOCALES[country] ?? [])[0];
+    const candidates = [appStoreGuess, appStoreGuess?.split("-")[0], project.spec.app.primaryLocale].filter(Boolean);
+    for (const c of candidates) {
+        const hit = available.find((l) => l.toLowerCase() === c.toLowerCase()) ?? available.find((l) => l.toLowerCase().startsWith(`${c.toLowerCase()}-`));
+        if (hit)
+            return hit;
+    }
+    return available[0];
+}
+/** App Store locale code → Google Play language code, where they differ. */
+const PLAY_LANGUAGE = {
+    tr: "tr-TR", ja: "ja-JP", ko: "ko-KR", it: "it-IT", ru: "ru-RU", uk: "uk", "zh-Hans": "zh-CN", "zh-Hant": "zh-TW",
+    "es-MX": "es-419", "ar-SA": "ar", he: "iw-IL", no: "no-NO", sv: "sv-SE", da: "da-DK", fi: "fi-FI", pl: "pl-PL",
+    cs: "cs-CZ", el: "el-GR", hu: "hu-HU", ro: "ro", th: "th", vi: "vi", id: "id", ms: "ms", hi: "hi-IN", ca: "ca",
+    hr: "hr", sk: "sk", "en-AU": "en-AU", "en-CA": "en-CA", "en-GB": "en-GB", "en-US": "en-US",
+};
+/** The Google Play language for an App Store locale (`tr` → `tr-TR`, `zh-Hans` → `zh-CN`). */
+export function playLanguageCode(appStoreLocale) {
+    return PLAY_LANGUAGE[appStoreLocale] ?? appStoreLocale;
+}
+//# sourceMappingURL=storefronts.js.map

package/dist/stores/app-store.d.ts

@@ -0,0 +1,33 @@
+import type { AppStoreListing, StoreListings } from "../schema.js";
+import type { OpsTransport } from "../transport.js";
+import type { FieldChange, PushResult, RemoteState, StoreAdapter } from "./types.js";
+export interface AppStoreContext {
+    version?: {
+        id: string;
+        versionString?: string;
+        state: string;
+        editable: boolean;
+    };
+    appInfo?: {
+        id: string;
+        state: string;
+        editable: boolean;
+    };
+    versionLocIds: Record<string, string>;
+    appInfoLocIds: Record<string, string>;
+}
+export declare class AppStoreAdapter implements StoreAdapter<AppStoreListing> {
+    private readonly transport;
+    private readonly appId;
+    private readonly platform;
+    readonly store: "app-store";
+    constructor(transport: OpsTransport, appId: string, platform?: string);
+    pull(): Promise<RemoteState<AppStoreListing>>;
+    /** Create the next App Store version so name, subtitle and keywords can change. */
+    createVersion(versionString: string): Promise<{
+        id: string;
+        versionString: string;
+    }>;
+    annotate(changes: FieldChange[], state: RemoteState<AppStoreListing>, local: StoreListings<AppStoreListing>): FieldChange[];
+    push(changes: FieldChange[], state: RemoteState<AppStoreListing>, local: StoreListings<AppStoreListing>): Promise<PushResult>;
+}

package/dist/stores/app-store.js

@@ -0,0 +1,159 @@
+import { LIVE_EDITABLE } from "../limits.js";
+/** Version and app info states in which App Store Connect accepts metadata edits. */
+const EDITABLE_STATES = new Set([
+    "PREPARE_FOR_SUBMISSION",
+    "DEVELOPER_REJECTED",
+    "REJECTED",
+    "METADATA_REJECTED",
+    "INVALID_BINARY",
+]);
+const LIVE_STATES = new Set(["READY_FOR_SALE", "READY_FOR_DISTRIBUTION", "ACCEPTED", "PROCESSING_FOR_DISTRIBUTION"]);
+const APP_INFO_FIELDS = new Set(["name", "subtitle"]);
+const VERSION_FIELDS = ["keywords", "promotionalText", "description", "whatsNew", "marketingUrl", "supportUrl"];
+function list(doc) {
+    if (!doc)
+        return [];
+    if (Array.isArray(doc))
+        return doc;
+    if (Array.isArray(doc.data))
+        return doc.data;
+    return doc.data ? [doc.data] : [];
+}
+function versionState(v) {
+    return v.attributes?.appVersionState ?? v.attributes?.appStoreState ?? "UNKNOWN";
+}
+function appInfoState(i) {
+    return i.attributes?.state ?? i.attributes?.appStoreState ?? "UNKNOWN";
+}
+function newestFirst(items) {
+    return [...items].sort((a, b) => (b.attributes?.createdDate ?? "").localeCompare(a.attributes?.createdDate ?? ""));
+}
+function clean(attrs, keys) {
+    const out = {};
+    for (const k of keys) {
+        const v = attrs?.[k];
+        if (typeof v === "string" && v !== "")
+            out[k] = v;
+    }
+    return out;
+}
+export class AppStoreAdapter {
+    transport;
+    appId;
+    platform;
+    store = "app-store";
+    constructor(transport, appId, platform = "IOS") {
+        this.transport = transport;
+        this.appId = appId;
+        this.platform = platform;
+    }
+    async pull() {
+        const versions = newestFirst(list(await this.transport.call("appstore_list_versions", { appId: this.appId, platform: this.platform })));
+        const version = versions.find((v) => EDITABLE_STATES.has(versionState(v))) ?? versions.find((v) => LIVE_STATES.has(versionState(v)));
+        const infos = list(await this.transport.call("appstore_list_app_infos", { appId: this.appId }));
+        const appInfo = infos.find((i) => EDITABLE_STATES.has(appInfoState(i))) ?? infos.find((i) => LIVE_STATES.has(appInfoState(i))) ?? infos[0];
+        const listings = {};
+        const context = { versionLocIds: {}, appInfoLocIds: {} };
+        if (version) {
+            const state = versionState(version);
+            context.version = { id: version.id, versionString: version.attributes?.versionString, state, editable: EDITABLE_STATES.has(state) };
+            const locs = list(await this.transport.call("appstore_list_version_localizations", { versionId: version.id, limit: 200 }));
+            for (const loc of locs) {
+                const locale = loc.attributes?.locale;
+                if (!locale)
+                    continue;
+                context.versionLocIds[locale] = loc.id;
+                listings[locale] = { ...listings[locale], ...clean(loc.attributes, VERSION_FIELDS) };
+            }
+        }
+        if (appInfo) {
+            const state = appInfoState(appInfo);
+            context.appInfo = { id: appInfo.id, state, editable: EDITABLE_STATES.has(state) };
+            const locs = list(await this.transport.call("appstore_list_app_info_localizations", { appInfoId: appInfo.id, limit: 200 }));
+            for (const loc of locs) {
+                const locale = loc.attributes?.locale;
+                if (!locale)
+                    continue;
+                context.appInfoLocIds[locale] = loc.id;
+                listings[locale] = { ...clean(loc.attributes, ["name", "subtitle"]), ...listings[locale] };
+            }
+        }
+        const target = context.version
+            ? `version ${context.version.versionString ?? context.version.id} (${context.version.state.toLowerCase().replace(/_/g, " ")})`
+            : "no App Store version found";
+        return { store: this.store, listings, target, context };
+    }
+    /** Create the next App Store version so name, subtitle and keywords can change. */
+    async createVersion(versionString) {
+        const created = await this.transport.call("appstore_create_version", { appId: this.appId, platform: this.platform, versionString }, { write: true });
+        const id = list(created)[0]?.id;
+        if (!id)
+            throw new Error(`App Store Connect did not return the new version ${versionString}.`);
+        return { id, versionString };
+    }
+    annotate(changes, state, local) {
+        const ctx = state.context;
+        return changes.map((c) => {
+            if (APP_INFO_FIELDS.has(c.field)) {
+                if (!ctx.appInfo)
+                    return { ...c, blocked: "This app has no app info in App Store Connect." };
+                if (!ctx.appInfo.editable) {
+                    return { ...c, blocked: "Name and subtitle change only with a new version. Create the next version in App Store Connect, then push again." };
+                }
+                if (!ctx.appInfoLocIds[c.locale] && !local[c.locale]?.name) {
+                    return { ...c, blocked: `Adding ${c.locale} needs a name in the spec.` };
+                }
+                return c;
+            }
+            if (!ctx.version)
+                return { ...c, blocked: "This app has no App Store version yet." };
+            if (!ctx.version.editable && !LIVE_EDITABLE["app-store"].has(c.field)) {
+                return {
+                    ...c,
+                    blocked: `${c.field} changes only with a new version (the current one is ${ctx.version.state.toLowerCase().replace(/_/g, " ")}). Create the next version, then push again.`,
+                };
+            }
+            return c;
+        });
+    }
+    async push(changes, state, local) {
+        const ctx = state.context;
+        const annotated = this.annotate(changes, state, local);
+        const ready = annotated.filter((c) => !c.blocked);
+        const skipped = annotated.filter((c) => c.blocked);
+        const applied = [];
+        for (const locale of [...new Set(ready.map((c) => c.locale))]) {
+            const mine = ready.filter((c) => c.locale === locale);
+            const infoFields = Object.fromEntries(mine.filter((c) => APP_INFO_FIELDS.has(c.field)).map((c) => [c.field, c.after]));
+            const versionFields = Object.fromEntries(mine.filter((c) => !APP_INFO_FIELDS.has(c.field)).map((c) => [c.field, c.after]));
+            if (Object.keys(infoFields).length > 0 && ctx.appInfo) {
+                const locId = ctx.appInfoLocIds[locale];
+                if (locId) {
+                    await this.transport.call("appstore_update_app_info_localization", { localizationId: locId, ...infoFields }, { write: true });
+                }
+                else {
+                    const created = await this.transport.call("appstore_create_app_info_localization", { appInfoId: ctx.appInfo.id, locale, name: local[locale]?.name, ...infoFields }, { write: true });
+                    const id = list(created)[0]?.id;
+                    if (id)
+                        ctx.appInfoLocIds[locale] = id;
+                }
+                applied.push(...mine.filter((c) => APP_INFO_FIELDS.has(c.field)));
+            }
+            if (Object.keys(versionFields).length > 0 && ctx.version) {
+                const locId = ctx.versionLocIds[locale];
+                if (locId) {
+                    await this.transport.call("appstore_update_version_localization", { localizationId: locId, ...versionFields }, { write: true });
+                }
+                else {
+                    const created = await this.transport.call("appstore_create_version_localization", { versionId: ctx.version.id, locale, ...versionFields }, { write: true });
+                    const id = list(created)[0]?.id;
+                    if (id)
+                        ctx.versionLocIds[locale] = id;
+                }
+                applied.push(...mine.filter((c) => !APP_INFO_FIELDS.has(c.field)));
+            }
+        }
+        return { applied, skipped };
+    }
+}
+//# sourceMappingURL=app-store.js.map

package/dist/stores/google-play.d.ts

@@ -0,0 +1,13 @@
+import type { GooglePlayListing, StoreListings } from "../schema.js";
+import type { OpsTransport } from "../transport.js";
+import type { FieldChange, PushResult, RemoteState, StoreAdapter } from "./types.js";
+export declare class GooglePlayAdapter implements StoreAdapter<GooglePlayListing> {
+    private readonly transport;
+    private readonly packageName;
+    readonly store: "google-play";
+    constructor(transport: OpsTransport, packageName: string);
+    pull(): Promise<RemoteState<GooglePlayListing>>;
+    annotate(changes: FieldChange[], _state: RemoteState<GooglePlayListing>, local: StoreListings<GooglePlayListing>): FieldChange[];
+    /** Google Play commits each language in its own edit; changes go live without an app update. */
+    push(changes: FieldChange[], state: RemoteState<GooglePlayListing>, local: StoreListings<GooglePlayListing>): Promise<PushResult>;
+}

package/dist/stores/google-play.js

@@ -0,0 +1,61 @@
+const REQUIRED_FOR_NEW = ["title", "shortDescription", "fullDescription"];
+function toListing(l) {
+    const out = {};
+    if (l.title)
+        out.title = l.title;
+    if (l.shortDescription)
+        out.shortDescription = l.shortDescription;
+    if (l.fullDescription)
+        out.fullDescription = l.fullDescription;
+    if (l.video)
+        out.video = l.video;
+    return out;
+}
+function rows(result) {
+    if (Array.isArray(result))
+        return result;
+    const wrapped = result;
+    return wrapped?.listings ?? wrapped?.data ?? [];
+}
+export class GooglePlayAdapter {
+    transport;
+    packageName;
+    store = "google-play";
+    constructor(transport, packageName) {
+        this.transport = transport;
+        this.packageName = packageName;
+    }
+    async pull() {
+        const listings = {};
+        for (const l of rows(await this.transport.call("gps_list_listings", { packageName: this.packageName }))) {
+            if (l.language)
+                listings[l.language] = toListing(l);
+        }
+        return { store: this.store, listings, target: `${this.packageName} (live listing)`, context: null };
+    }
+    annotate(changes, _state, local) {
+        return changes.map((c) => {
+            if (!c.newLocale)
+                return c;
+            const missing = REQUIRED_FOR_NEW.filter((f) => !local[c.locale]?.[f]);
+            return missing.length > 0 ? { ...c, blocked: `A new Google Play language needs ${missing.join(", ")} in the spec.` } : c;
+        });
+    }
+    /** Google Play commits each language in its own edit; changes go live without an app update. */
+    async push(changes, state, local) {
+        const annotated = this.annotate(changes, state, local);
+        const ready = annotated.filter((c) => !c.blocked);
+        const skipped = annotated.filter((c) => c.blocked);
+        const applied = [];
+        for (const language of [...new Set(ready.map((c) => c.locale))]) {
+            const mine = ready.filter((c) => c.locale === language);
+            const fields = mine[0].newLocale
+                ? { ...local[language] }
+                : Object.fromEntries(mine.map((c) => [c.field, c.after]));
+            await this.transport.call("gps_update_listing", { packageName: this.packageName, language, ...fields }, { write: true });
+            applied.push(...mine);
+        }
+        return { applied, skipped };
+    }
+}
+//# sourceMappingURL=google-play.js.map

package/dist/stores/types.d.ts

@@ -0,0 +1,34 @@
+import type { Listing, StoreId, StoreListings } from "../schema.js";
+/** One field that differs between the spec and the store. */
+export interface FieldChange {
+    store: StoreId;
+    locale: string;
+    field: string;
+    /** Live value; undefined when the store has no value or no such locale. */
+    before: string | undefined;
+    after: string;
+    /** The locale does not exist in the store yet. */
+    newLocale: boolean;
+    /** Why this change cannot be pushed right now, if it cannot. */
+    blocked?: string;
+}
+/** What the store looks like now, plus whatever the adapter needs to write back. */
+export interface RemoteState<L extends Listing = Listing> {
+    store: StoreId;
+    listings: StoreListings<L>;
+    /** Human-readable context, e.g. which App Store version is being edited. */
+    target: string;
+    /** Adapter-private data (resource ids, editability). */
+    context: unknown;
+}
+export interface PushResult {
+    applied: FieldChange[];
+    skipped: FieldChange[];
+}
+export interface StoreAdapter<L extends Listing = Listing> {
+    readonly store: StoreId;
+    pull(): Promise<RemoteState<L>>;
+    /** Mark changes that cannot be written in the current store state. */
+    annotate(changes: FieldChange[], state: RemoteState<L>, local: StoreListings<L>): FieldChange[];
+    push(changes: FieldChange[], state: RemoteState<L>, local: StoreListings<L>): Promise<PushResult>;
+}

package/dist/stores/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/suggest.d.ts

@@ -0,0 +1,73 @@
+import type { Project, StoreId } from "./schema.js";
+/** Add one word to an App Store keyword field the compact way (`a,b,c`), or return null when it does not fit. */
+export declare function appendKeyword(field: string | undefined, word: string, maxChars?: number): string | null;
+export interface KeywordSuggestion {
+    word: string;
+    /** Targets that this word would help cover. */
+    helps: string[];
+    popularity?: number;
+    /** True when the word still fits in the keyword field. */
+    fits: boolean;
+    /** True when one of your own targets needs it (ranked before API candidates). */
+    target: boolean;
+}
+export interface CandidateKeyword {
+    keyword: string;
+    popularity?: number;
+    /** "suggestion" for store autocomplete ideas, which must relate to the listing to count. */
+    source?: string;
+}
+/**
+ * Words to add to one App Store locale's keyword field: the missing words of
+ * targets in storefronts that index this locale, plus extra candidates (for
+ * example keyword opportunities from the Appeeky API). Words already indexed
+ * anywhere in the locale are left out.
+ *
+ * An autocomplete idea only counts when it shares a word with the listing or
+ * the targets: "screenshot stitching" is an idea for a screenshot app, "proton
+ * vpn" (another product the store's autocomplete returned) is not. Searches
+ * the app already ranks for always count.
+ */
+export declare function keywordSuggestions(project: Project, locale: string, candidates?: CandidateKeyword[]): KeywordSuggestion[];
+export interface CrossLocalizationSuggestion {
+    country: string;
+    /** The secondary locale whose keyword field gets the words. */
+    locale: string;
+    add: string[];
+    /** The keyword field after adding them. */
+    keywords: string;
+    /** The field was one long phrase without commas; `keywords` also splits it into words. */
+    splitPhrase?: boolean;
+}
+/**
+ * A keyword field written without commas reads as one long phrase. Split it
+ * into comma-separated words so each word can combine with others.
+ */
+export declare function splitKeywordPhrase(field: string): string | null;
+/**
+ * Storefronts that index more than one locale (the US reads Spanish (Mexico)
+ * too) get extra keyword space for free. Fill the spare characters of the secondary
+ * locale with words the storefront's targets still miss.
+ */
+export declare function crossLocalizationSuggestions(project: Project): CrossLocalizationSuggestion[];
+/** A competitor metadata change, as recorded by Appeeky's competitor timeline. */
+export interface CompetitorChange {
+    competitor: string;
+    field: string;
+    before: string | null;
+    after: string | null;
+    at: string;
+}
+export interface CompetitorGap {
+    competitor: string;
+    field: string;
+    at: string;
+    /** Words the competitor stopped using that one of your targets needs. */
+    dropped: string[];
+    /** Words the competitor started using that one of your targets needs. */
+    added: string[];
+    /** Of the dropped words, those your listing does not index yet. */
+    openings: string[];
+}
+/** Turn competitor metadata changes into openings for one storefront's targets. */
+export declare function competitorGaps(project: Project, country: string, changes: CompetitorChange[], store?: StoreId): CompetitorGap[];

package/dist/suggest.js

@@ -0,0 +1,135 @@
+import { appStoreCoverage, googlePlayCoverage, isCovered } from "./coverage.js";
+import { indexedLocales } from "./storefronts.js";
+import { charLength, keywordEntries, STOPWORDS, unique, words } from "./text.js";
+/** Add one word to an App Store keyword field the compact way (`a,b,c`), or return null when it does not fit. */
+export function appendKeyword(field, word, maxChars = 100) {
+    const entries = keywordEntries(field);
+    if (entries.some((e) => e.toLowerCase() === word.toLowerCase()))
+        return entries.join(",");
+    const next = [...entries, word].join(",");
+    return charLength(next) <= maxChars ? next : null;
+}
+/** Words of the locale's indexed fields (App Store: name, subtitle, keyword field). */
+function indexedWords(project, locale) {
+    const l = project.listings["app-store"][locale] ?? {};
+    return new Set([...words(l.name), ...words(l.subtitle), ...keywordEntries(l.keywords).flatMap((e) => words(e))]);
+}
+/**
+ * Words to add to one App Store locale's keyword field: the missing words of
+ * targets in storefronts that index this locale, plus extra candidates (for
+ * example keyword opportunities from the Appeeky API). Words already indexed
+ * anywhere in the locale are left out.
+ *
+ * An autocomplete idea only counts when it shares a word with the listing or
+ * the targets: "screenshot stitching" is an idea for a screenshot app, "proton
+ * vpn" (another product the store's autocomplete returned) is not. Searches
+ * the app already ranks for always count.
+ */
+export function keywordSuggestions(project, locale, candidates = []) {
+    const have = indexedWords(project, locale);
+    const field = project.listings["app-store"][locale]?.keywords;
+    const out = new Map();
+    const add = (word, helps, popularity, target) => {
+        if (have.has(word) || word.length < 2 || STOPWORDS.has(word))
+            return;
+        const s = out.get(word) ?? { word, helps: [], fits: appendKeyword(field, word) !== null, target };
+        s.target ||= target;
+        if (!s.helps.includes(helps))
+            s.helps.push(helps);
+        if (popularity !== undefined)
+            s.popularity = Math.max(s.popularity ?? 0, popularity);
+        out.set(word, s);
+    };
+    for (const country of Object.keys(project.spec.targets)) {
+        if (!indexedLocales(project, country).includes(locale))
+            continue;
+        for (const k of appStoreCoverage(project, country).keywords) {
+            if (!isCovered(k.level))
+                for (const w of k.missing)
+                    add(w, k.keyword, k.popularity, true);
+        }
+    }
+    const related = new Set([...have, ...Object.values(project.spec.targets).flatMap((list) => list.flatMap((t) => words(t)))].filter((w) => !STOPWORDS.has(w)));
+    for (const c of candidates) {
+        const cw = words(c.keyword);
+        if (c.source === "suggestion" && !cw.some((w) => related.has(w)))
+            continue;
+        for (const w of cw)
+            add(w, c.keyword, c.popularity, false);
+    }
+    return [...out.values()].sort((a, b) => Number(b.fits) - Number(a.fits) ||
+        Number(b.target) - Number(a.target) ||
+        (b.popularity ?? 0) - (a.popularity ?? 0) ||
+        b.helps.length - a.helps.length);
+}
+/**
+ * A keyword field written without commas reads as one long phrase. Split it
+ * into comma-separated words so each word can combine with others.
+ */
+export function splitKeywordPhrase(field) {
+    const entries = keywordEntries(field);
+    if (entries.length !== 1 || !/\s/.test(entries[0]))
+        return null;
+    return unique(words(entries[0])).join(",");
+}
+/**
+ * Storefronts that index more than one locale (the US reads Spanish (Mexico)
+ * too) get extra keyword space for free. Fill the spare characters of the secondary
+ * locale with words the storefront's targets still miss.
+ */
+export function crossLocalizationSuggestions(project) {
+    const out = [];
+    for (const country of Object.keys(project.spec.targets)) {
+        const present = indexedLocales(project, country);
+        // The first locale is the storefront's own; the rest are extra keyword space.
+        const secondary = present.slice(1);
+        if (secondary.length === 0)
+            continue;
+        const covered = new Set(present.flatMap((l) => [...indexedWords(project, l)]));
+        const missing = unique(appStoreCoverage(project, country)
+            .keywords.filter((k) => !isCovered(k.level))
+            .flatMap((k) => words(k.keyword))
+            .filter((w) => !covered.has(w) && !STOPWORDS.has(w)));
+        for (const locale of secondary) {
+            const original = project.listings["app-store"][locale]?.keywords ?? "";
+            const split = splitKeywordPhrase(original);
+            let field = split ?? original;
+            const added = [];
+            for (const w of missing) {
+                if (out.some((s) => s.country === country && s.add.includes(w)))
+                    continue;
+                const next = appendKeyword(field, w);
+                if (next === null)
+                    continue;
+                field = next;
+                added.push(w);
+            }
+            if (added.length > 0)
+                out.push({ country, locale, add: added, keywords: field, ...(split ? { splitPhrase: true } : {}) });
+        }
+    }
+    return out;
+}
+/** Turn competitor metadata changes into openings for one storefront's targets. */
+export function competitorGaps(project, country, changes, store = "app-store") {
+    const targetWords = new Set((project.spec.targets[country] ?? []).flatMap((k) => words(k)));
+    if (targetWords.size === 0)
+        return [];
+    const report = store === "app-store" ? appStoreCoverage(project, country) : googlePlayCoverage(project, country);
+    const missing = new Set(report.keywords.flatMap((k) => k.missing));
+    const gaps = [];
+    for (const ch of changes) {
+        // A change with one side missing is not a change we can read words from.
+        if (!ch.before || !ch.after)
+            continue;
+        const before = new Set(words(ch.before ?? ""));
+        const after = new Set(words(ch.after ?? ""));
+        const dropped = [...before].filter((w) => !after.has(w) && targetWords.has(w));
+        const added = [...after].filter((w) => !before.has(w) && targetWords.has(w));
+        if (dropped.length === 0 && added.length === 0)
+            continue;
+        gaps.push({ competitor: ch.competitor, field: ch.field, at: ch.at, dropped, added, openings: dropped.filter((w) => missing.has(w)) });
+    }
+    return gaps;
+}
+//# sourceMappingURL=suggest.js.map

package/dist/text.d.ts

@@ -0,0 +1,18 @@
+/** Text helpers shared by the lint rules and the coverage report. */
+/** UTF-8 byte length: the unit Apple uses for the 100-byte keyword field. */
+export declare function byteLength(value: string): number;
+/** Character count as the stores count it (user-perceived characters, not UTF-16 units). */
+export declare function charLength(value: string): number;
+export declare function normalize(value: string): string;
+/** Lowercased words; punctuation and symbols split words, apostrophes inside a word are kept. */
+export declare function words(value: string | undefined): string[];
+/** Entries of an App Store keyword field, as written (trimmed, empty ones dropped). */
+export declare function keywordEntries(field: string | undefined): string[];
+/** Naive English singular form, only used to flag likely plural pairs. */
+export declare function singular(word: string): string;
+export declare function isEnglish(locale: string): boolean;
+export declare function unique<T>(items: Iterable<T>): T[];
+/** Short English words that do not decide a search; ignored when a phrase has other words. */
+export declare const STOPWORDS: Set<string>;
+/** Words of a target that matter for coverage: stopwords drop out unless they are all there is. */
+export declare function keyWords(value: string): string[];