earnrate 0.2.5 → 0.2.7

package/dist/merchants/missed.js

@@ -0,0 +1,78 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { z } from 'zod';
+import { CONFIG_DIR, MISSED_ENV_VAR } from "../brand.js";
+import { normalizeMerchantName } from "./resolve.js";
+const MissedFileSchema = z.object({
+    version: z.literal(1),
+    merchants: z.record(z.string(), z.object({
+        name: z.string(),
+        count: z.number().int().positive(),
+        last_seen: z.string(),
+        categories: z.array(z.string()).default([]),
+    })),
+});
+const MAX = 500;
+// $EARNRATE_MISSED_MERCHANTS names another file, or "off" keeps no log.
+export function missedPath(env = process.env) {
+    const given = env[MISSED_ENV_VAR]?.trim();
+    if (given === 'off')
+        return null;
+    return given || path.join(homedir(), CONFIG_DIR, 'missed-merchants.json');
+}
+export async function readMissed(file) {
+    try {
+        const parsed = MissedFileSchema.safeParse(JSON.parse(await readFile(file, 'utf8')));
+        return parsed.success ? Object.values(parsed.data.merchants) : [];
+    }
+    catch {
+        return [];
+    }
+}
+// Writes are queued, so concurrent tool calls never lose a count. A file that
+// can't be read as a log is left alone.
+export function missLogAt(file) {
+    let queue = Promise.resolve();
+    return {
+        note(name, category, today) {
+            const key = normalizeMerchantName(name);
+            if (key === '')
+                return Promise.resolve();
+            const run = queue.then(async () => {
+                let merchants = {};
+                try {
+                    const parsed = MissedFileSchema.safeParse(JSON.parse(await readFile(file, 'utf8')));
+                    if (!parsed.success)
+                        return;
+                    merchants = parsed.data.merchants;
+                }
+                catch (e) {
+                    if (!(e instanceof Error && 'code' in e && e.code === 'ENOENT'))
+                        return;
+                }
+                const seen = merchants[key];
+                merchants[key] = {
+                    name: name.trim(),
+                    count: (seen?.count ?? 0) + 1,
+                    last_seen: today,
+                    categories: [
+                        ...new Set([
+                            ...(seen?.categories ?? []),
+                            ...(category === null ? [] : [category]),
+                        ]),
+                    ],
+                };
+                const kept = Object.entries(merchants)
+                    .sort(([, a], [, b]) => b.last_seen.localeCompare(a.last_seen))
+                    .slice(0, MAX);
+                await mkdir(path.dirname(file), { recursive: true });
+                const tmp = `${file}.${String(process.pid)}.tmp`;
+                await writeFile(tmp, `${JSON.stringify({ version: 1, merchants: Object.fromEntries(kept) }, null, 2)}\n`);
+                await rename(tmp, file);
+            });
+            queue = run.catch(() => undefined);
+            return run.catch(() => undefined);
+        },
+    };
+}

package/dist/merchants/resolve.js

@@ -116,17 +116,94 @@ function fromMerchant(found, source, input, channel, typedDomain) {
         inference: null,
     };
 }
+// A merchant's record by id; an override replaces the seed entry.
+export function findMerchant(catalog, id) {
+    return (catalog.merchants.overrides.find((m) => m.id === id) ??
+        catalog.merchants.seed.find((m) => m.id === id));
+}
 export function resolveMerchantById(catalog, id, channel) {
     const override = catalog.merchants.overrides.find((m) => m.id === id);
-    const found = override ?? catalog.merchants.seed.find((m) => m.id === id);
+    const found = findMerchant(catalog, id);
     if (!found)
         return null;
     return fromMerchant(found, override ? 'override' : 'seed', found.name, channel, false);
 }
-// Used only when the merchant is unknown: curated data always wins over a
-// category supplied with the request.
+// Curated merchant data always wins over a category supplied with the
+// request; the caller's category wins over an unknown name or a different
+// category word.
 export function withCallerCategory(merchant, category) {
-    if (merchant.source !== 'none' || category === null)
+    if (category === null)
+        return merchant;
+    const otherWord = merchant.source === 'category' && merchant.category !== category;
+    if (merchant.source !== 'none' && !otherWord)
         return merchant;
     return { ...merchant, category, confidence: 'medium', source: 'caller' };
 }
+const plainWords = (s) => s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+// A category from everyday words: an alias ("groceries") first, then the
+// name, then the id, so "grocery" means supermarkets rather than the parent.
+export function findCategory(catalog, text) {
+    const wanted = plainWords(text);
+    if (wanted === '')
+        return null;
+    // "grocery store" finds "grocery stores", and "drugstore" "drugstores".
+    const forms = [
+        wanted,
+        wanted.endsWith('s') ? wanted.slice(0, -1) : `${wanted}s`,
+    ];
+    for (const form of forms) {
+        const by = (key) => catalog.categories.find((c) => key(c).map(plainWords).includes(form))?.id;
+        const found = by((c) => c.aliases) ?? by((c) => [c.name]) ?? by((c) => [c.id]);
+        if (found !== undefined)
+            return found;
+    }
+    return null;
+}
+export function categoryResolution(catalog, category, channel) {
+    const found = catalog.categories.find((c) => c.id === category);
+    if (!found)
+        throw new Error(`unknown category '${category}'`);
+    return {
+        input: found.name,
+        merchantId: null,
+        resolvedName: found.name,
+        category,
+        likelyMcc: null,
+        accepts: null,
+        ambiguity: null,
+        channel,
+        confidence: 'high',
+        source: 'category',
+        bookedVia: [],
+        inference: null,
+    };
+}
+// Words around a place that don't name it: "a restaurant", "the grocery
+// store", "a gas station near me".
+const LEADING = /^(?:(?:a|an|the|my|any|some|our|your|this|that|local|nearby|nearest)\s+)+/i;
+const TRAILING = /\s+(?:near me|nearby|around here|close by)$/i;
+// What someone typed: a store earnrate knows, else a category word
+// ("restaurants", "gas"), else unrecognized. Names are tried as given first,
+// so a store like The Home Depot keeps its "The".
+export function resolvePlace(catalog, text, channel) {
+    const attempt = (t) => {
+        const known = resolveMerchant(catalog, t, channel);
+        if (known.source !== 'none')
+            return known;
+        const category = findCategory(catalog, t);
+        return category === null
+            ? known
+            : categoryResolution(catalog, category, channel);
+    };
+    const asGiven = attempt(text);
+    if (asGiven.source !== 'none')
+        return asGiven;
+    const bare = text.trim().replace(TRAILING, '').replace(LEADING, '');
+    if (bare === '' || bare === text.trim())
+        return asGiven;
+    const found = attempt(bare);
+    return found.source === 'none' ? asGiven : found;
+}

package/dist/schema/card.js

@@ -58,12 +58,15 @@ export const RuleSchema = z
         .optional(),
     valid_from: IsoDate.optional(),
     valid_to: IsoDate.optional(),
+    // The issuer's last day to activate a bonus that needs it.
+    activate_by: IsoDate.optional(),
     // Set when a rule isn't confirmed against the issuer's terms. The engine
     // warns when an unverified rule decides the winner.
     unverified: z.string().optional(),
     note: z.string().optional(),
 })
-    .refine((r) => !r.valid_from || !r.valid_to || r.valid_from <= r.valid_to, 'valid_from must not be after valid_to');
+    .refine((r) => !r.valid_from || !r.valid_to || r.valid_from <= r.valid_to, 'valid_from must not be after valid_to')
+    .refine((r) => r.activate_by === undefined || r.requires?.activation === true, 'activate_by needs requires.activation');
 // The public sign-up bonus on the issuer's page. Offers vary by person and
 // channel, so a wallet can override it.
 export const WelcomeOfferSchema = z

package/dist/schema/issuer.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import { KebabId } from "./common.js";
+export const IssuerSchema = z.strictObject({
+    id: KebabId,
+    name: z.string().min(1), // as shown: "American Express"
+    search: z.array(z.string().min(1)).default([]), // other words people use
+});
+export const IssuersFileSchema = z.array(IssuerSchema).min(1);

package/dist/schema/wallet.js

@@ -49,5 +49,5 @@ export const WalletSchema = z.strictObject({
     version: z.number().int().positive().optional(),
     valuations: z.record(CurrencyId, Valuation).default({}),
     memberships: z.array(KebabId).default([]),
-    cards: z.array(WalletCardSchema).min(1),
+    cards: z.array(WalletCardSchema).default([]),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "earnrate",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Which credit card earns the most at a merchant, from your cards or every card, and why",
   "keywords": [
     "credit cards",