dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/data/src/watchlist.js

@@ -0,0 +1,176 @@
+// Persisted watchlist + alert proposals (task-1298, SPEC §4.5). `node:sqlite`, same file as the cache
+// (default XDG path) so one `--db` controls everything. Tables:
+//   watchlist(mint PK, symbol, name, launchpad, added_at, entry_price, note)
+//   alert_rules(id, mint, kind, op, value, status proposed|armed|fired|dismissed, created_at, note)
+//   alert_events(id, t, mint, kind, level, text)
+// Rules: proposals are only ever *proposed* by code (or later by the Analyst); a user keypress arms
+// them. Firing a rule writes an event and marks the rule `fired` (one shot). Nothing here trades.
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { systemClock } from "./clock.js";
+export class WatchlistStore {
+    db;
+    clock;
+    constructor(opts = {}) {
+        const path = opts.path ?? ':memory:';
+        if (path !== ':memory:')
+            mkdirSync(dirname(path), { recursive: true });
+        this.db = new DatabaseSync(path);
+        this.clock = opts.clock ?? systemClock;
+        this.db.exec(`
+      PRAGMA journal_mode = WAL;
+      CREATE TABLE IF NOT EXISTS watchlist (
+        mint TEXT PRIMARY KEY, symbol TEXT NOT NULL, name TEXT NOT NULL, launchpad TEXT NOT NULL,
+        added_at INTEGER NOT NULL, entry_price REAL, note TEXT NOT NULL DEFAULT ''
+      ) WITHOUT ROWID;
+      CREATE TABLE IF NOT EXISTS alert_rules (
+        id INTEGER PRIMARY KEY AUTOINCREMENT, mint TEXT NOT NULL, kind TEXT NOT NULL, op TEXT NOT NULL, value REAL NOT NULL,
+        status TEXT NOT NULL, created_at INTEGER NOT NULL, note TEXT NOT NULL DEFAULT ''
+      );
+      CREATE INDEX IF NOT EXISTS alert_rules_mint ON alert_rules(mint, status);
+      CREATE TABLE IF NOT EXISTS alert_events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT, t INTEGER NOT NULL, mint TEXT, kind TEXT NOT NULL, level TEXT NOT NULL, text TEXT NOT NULL
+      );
+    `);
+    }
+    // ---------------------------------------------------------------- watchlist
+    list() {
+        const rows = this.db.prepare('SELECT mint, symbol, name, launchpad, added_at, entry_price, note FROM watchlist ORDER BY added_at DESC').all();
+        return rows.map(rowToEntry);
+    }
+    get(mint) {
+        const row = this.db.prepare('SELECT mint, symbol, name, launchpad, added_at, entry_price, note FROM watchlist WHERE mint = ?').get(mint);
+        return row ? rowToEntry(row) : undefined;
+    }
+    has(mint) {
+        return this.get(mint) !== undefined;
+    }
+    /** Insert (or update identity fields of) a watched token. Returns true when it was new. */
+    add(e) {
+        const existed = this.has(e.mint);
+        if (existed) {
+            this.db.prepare('UPDATE watchlist SET symbol = ?, name = ?, launchpad = ? WHERE mint = ?').run(e.symbol, e.name, e.launchpad, e.mint);
+            return false;
+        }
+        this.db
+            .prepare('INSERT INTO watchlist (mint, symbol, name, launchpad, added_at, entry_price, note) VALUES (?, ?, ?, ?, ?, ?, ?)')
+            .run(e.mint, e.symbol, e.name, e.launchpad, this.clock.now(), e.entryPrice, e.note ?? '');
+        return true;
+    }
+    remove(mint) {
+        const r = this.db.prepare('DELETE FROM watchlist WHERE mint = ?').run(mint);
+        this.db.prepare("UPDATE alert_rules SET status = 'dismissed' WHERE mint = ? AND status IN ('proposed', 'armed')").run(mint);
+        return Number(r.changes) > 0;
+    }
+    setNote(mint, note) {
+        this.db.prepare('UPDATE watchlist SET note = ? WHERE mint = ?').run(note, mint);
+    }
+    setEntry(mint, entryPrice) {
+        this.db.prepare('UPDATE watchlist SET entry_price = ? WHERE mint = ?').run(entryPrice, mint);
+    }
+    // ---------------------------------------------------------------- alert rules
+    /** Record a proposal. Nothing fires until confirm() arms it. */
+    propose(r) {
+        const res = this.db
+            .prepare("INSERT INTO alert_rules (mint, kind, op, value, status, created_at, note) VALUES (?, ?, ?, ?, 'proposed', ?, ?)")
+            .run(r.mint, r.kind, r.op, r.value, this.clock.now(), r.note ?? '');
+        return this.rule(Number(res.lastInsertRowid));
+    }
+    confirm(id) {
+        this.db.prepare("UPDATE alert_rules SET status = 'armed' WHERE id = ? AND status = 'proposed'").run(id);
+        return this.rule(id);
+    }
+    dismiss(id) {
+        this.db.prepare("UPDATE alert_rules SET status = 'dismissed' WHERE id = ? AND status IN ('proposed', 'armed')").run(id);
+        return this.rule(id);
+    }
+    rule(id) {
+        const row = this.db.prepare('SELECT id, mint, kind, op, value, status, created_at, note FROM alert_rules WHERE id = ?').get(id);
+        return row ? rowToRule(row) : undefined;
+    }
+    rules(status, mint) {
+        const statuses = status === undefined ? null : Array.isArray(status) ? status : [status];
+        const where = [];
+        const args = [];
+        if (statuses) {
+            where.push(`status IN (${statuses.map(() => '?').join(',')})`);
+            args.push(...statuses);
+        }
+        if (mint) {
+            where.push('mint = ?');
+            args.push(mint);
+        }
+        const sql = `SELECT id, mint, kind, op, value, status, created_at, note FROM alert_rules${where.length ? ' WHERE ' + where.join(' AND ') : ''} ORDER BY id ASC`;
+        return this.db.prepare(sql).all(...args).map(rowToRule);
+    }
+    /**
+     * Evaluate the armed rules against current values; each rule that trips fires once (status `fired`)
+     * and writes an event. `values` maps mint -> {price, liq, holders, mcap} with nulls for unknowns.
+     */
+    evaluate(values, symbolOf = (m) => m.slice(0, 6)) {
+        const fired = [];
+        for (const r of this.rules('armed')) {
+            const v = values.get(r.mint)?.[r.kind];
+            if (v === null || v === undefined || !Number.isFinite(v))
+                continue;
+            const hit = r.op === '>' ? v > r.value : v < r.value;
+            if (!hit)
+                continue;
+            this.db.prepare("UPDATE alert_rules SET status = 'fired' WHERE id = ?").run(r.id);
+            const level = r.kind === 'price' || r.kind === 'mcap' ? (r.op === '>' ? 'up' : 'down') : r.op === '<' ? 'down' : 'info';
+            fired.push(this.log({ mint: r.mint, kind: r.kind, level, text: `${symbolOf(r.mint)} ${r.kind} ${r.op} ${fmtValue(r.kind, r.value)} (now ${fmtValue(r.kind, v)})` }));
+        }
+        return fired;
+    }
+    // ---------------------------------------------------------------- events
+    log(e) {
+        const t = this.clock.now();
+        const res = this.db.prepare('INSERT INTO alert_events (t, mint, kind, level, text) VALUES (?, ?, ?, ?, ?)').run(t, e.mint, e.kind, e.level, e.text);
+        return { id: Number(res.lastInsertRowid), t, mint: e.mint, kind: e.kind, level: e.level, text: e.text };
+    }
+    events(limit = 50) {
+        const rows = this.db.prepare('SELECT id, t, mint, kind, level, text FROM alert_events ORDER BY id DESC LIMIT ?').all(limit);
+        return rows.map((r) => ({ id: Number(r.id), t: Number(r.t), mint: r.mint ?? null, kind: String(r.kind), level: r.level, text: String(r.text) }));
+    }
+    close() {
+        this.db.close();
+    }
+}
+function rowToEntry(r) {
+    return {
+        mint: String(r.mint),
+        symbol: String(r.symbol),
+        name: String(r.name),
+        launchpad: r.launchpad,
+        addedAt: Number(r.added_at),
+        entryPrice: r.entry_price === null || r.entry_price === undefined ? null : Number(r.entry_price),
+        note: String(r.note ?? ''),
+    };
+}
+function rowToRule(r) {
+    return {
+        id: Number(r.id),
+        mint: String(r.mint),
+        kind: r.kind,
+        op: r.op,
+        value: Number(r.value),
+        status: r.status,
+        createdAt: Number(r.created_at),
+        note: String(r.note ?? ''),
+    };
+}
+export function fmtValue(kind, v) {
+    if (kind === 'holders')
+        return String(Math.round(v));
+    if (kind === 'price')
+        return v >= 1 ? `$${v.toFixed(2)}` : `$${v.toPrecision(3)}`;
+    const a = Math.abs(v);
+    if (a >= 1e9)
+        return `$${(v / 1e9).toFixed(1)}B`;
+    if (a >= 1e6)
+        return `$${(v / 1e6).toFixed(1)}M`;
+    if (a >= 1e3)
+        return `$${(v / 1e3).toFixed(0)}K`;
+    return `$${v.toFixed(0)}`;
+}

package/dist/packages/data/src/x/api.js

@@ -0,0 +1,256 @@
+// @dexterm/data — the user-authorized X v2 read adapter (task-1357, lane I-02; INTEGRATIONS-DESIGN §4).
+//
+// Only these official endpoints, only in USER context (the user's own login, their rate windows, their bill):
+//   GET /2/users/me                       identity (75 / 15 min)
+//   GET /2/tweets/search/recent           per-token panel, `from:` KOL queries (300 / 15 min per user, 7 days)
+//   GET /2/lists/:id/tweets               the user's own X lists as KOL feeds (900 / 15 min)
+//   GET /2/users/:id/owned_lists          import own lists (15 / 15 min)
+//   GET /2/lists/:id/members              the list's handles (900 / 15 min)
+// Never: posting, liking, following, DMs, streams (economically unbounded), scraping of x.com pages.
+//
+// Every call: health gate + limiter bucket `x-api` → bearer from the OAuth client (refreshed near expiry) →
+// node transport → the X rate-limit headers update a per-endpoint window → the spend meter counts NEW post ids
+// → 15-minute query cache in the shared DB so re-opening a token is free. 401 = logged out (the user revoked
+// at x.com); 429 = rate-limited until `x-rate-limit-reset`; 403 client-not-enrolled = the app's tier cannot
+// read this endpoint (X Free tier: no search/list timelines). Each is a typed XApiError the poller turns into
+// a VISIBLE state — never a silent empty feed. Raw tweet text leaves this module only as a RawPost, which the
+// social feed firewalls on ingest; no tweet text is ever logged.
+import { systemClock } from "../clock.js";
+import { X_LIVE_ENDPOINTS, redactXSecrets } from "./config.js";
+import { XAuthError } from "./oauth.js";
+import { nodeXTransport } from "./transport.js";
+export const X_BUCKET = 'x-api';
+export const X_QUERY_NS = 'x:query';
+export const X_QUERY_TTL_MS = 15 * 60_000;
+export const X_SEARCH_MAX = 100;
+export const X_TWEET_FIELDS = 'created_at,public_metrics,lang,author_id';
+export const X_USER_FIELDS = 'created_at,username,name';
+export class XApiError extends Error {
+    kind;
+    status;
+    /** Epoch ms when a rate-limited window resets (429 only). */
+    resetAt;
+    constructor(kind, message, status = null, resetAt = null) {
+        super(redactXSecrets(message));
+        this.name = 'XApiError';
+        this.kind = kind;
+        this.status = status;
+        this.resetAt = resetAt;
+    }
+}
+export class XApi {
+    endpoints;
+    oauth;
+    transport;
+    limiter;
+    health;
+    cache;
+    spend;
+    clock;
+    env;
+    queryTtlMs;
+    onRequest;
+    /** Per-endpoint windows from the last response headers (`search`, `list-tweets`, `me`, …). */
+    windows = new Map();
+    constructor(opts) {
+        this.oauth = opts.oauth;
+        this.endpoints = opts.endpoints ?? opts.oauth.endpoints ?? X_LIVE_ENDPOINTS;
+        this.transport = opts.transport ?? nodeXTransport();
+        this.limiter = opts.limiter ?? null;
+        this.health = opts.health ?? null;
+        this.cache = opts.cache ?? null;
+        this.spend = opts.spend ?? null;
+        this.clock = opts.clock ?? systemClock;
+        this.env = opts.env ?? process.env;
+        this.queryTtlMs = opts.queryTtlMs ?? X_QUERY_TTL_MS;
+        this.onRequest = opts.onRequest;
+    }
+    /** The window for an endpoint key, or null when never seen / already reset. */
+    window(key) {
+        const w = this.windows.get(key);
+        if (!w)
+            return null;
+        if (w.resetAt !== null && this.clock.now() >= w.resetAt)
+            return null;
+        return w;
+    }
+    noteWindow(key, res) {
+        const num = (h) => { const v = Number(res.headers[h]); return Number.isFinite(v) ? v : null; };
+        const reset = num('x-rate-limit-reset');
+        this.windows.set(key, { limit: num('x-rate-limit-limit'), remaining: num('x-rate-limit-remaining'), resetAt: reset !== null ? reset * 1000 : null, seenAt: this.clock.now() });
+    }
+    /** One authenticated GET. Throws XApiError; never logs a token or a tweet. */
+    async get(key, path, params) {
+        if (this.health && !this.health.isAvailable('x-api'))
+            throw new XApiError('unavailable', `x-api is ${this.health.state('x-api')}`);
+        if (this.spend && !this.spend.allow())
+            throw new XApiError('no-credit', `daily X budget reached ($${this.spend.budgetUsd} — DEXTERM_X_DAILY_USD); reads resume at the next UTC day`);
+        const w = this.window(key);
+        if (w && w.remaining !== null && w.remaining <= 0 && w.resetAt !== null)
+            throw new XApiError('rate-limited', `${key}: window exhausted`, 429, w.resetAt);
+        let bearer;
+        try {
+            bearer = await this.oauth.bearer(this.env);
+        }
+        catch (e) {
+            if (e instanceof XAuthError && (e.kind === 'not-logged-in'))
+                throw new XApiError('unauthorized', 'not logged in', 401);
+            throw new XApiError('unauthorized', `token refresh failed: ${e instanceof Error ? e.message : String(e)}`, 401);
+        }
+        if (this.limiter)
+            await this.limiter.acquire(X_BUCKET);
+        const url = `${this.endpoints.api}${path}?${new URLSearchParams(params).toString()}`;
+        let res;
+        try {
+            res = await this.transport({ method: 'GET', url, headers: { authorization: `Bearer ${bearer}` } });
+        }
+        catch (e) {
+            const msg = redactXSecrets(e instanceof Error ? e.message : String(e));
+            this.health?.record('x-api', { ok: false, error: msg });
+            this.onRequest?.({ endpoint: key, status: null, latencyMs: 0, cached: false });
+            throw new XApiError('transport', msg);
+        }
+        this.onRequest?.({ endpoint: key, status: res.status, latencyMs: res.latencyMs, cached: false });
+        this.noteWindow(key, res);
+        let body = {};
+        try {
+            body = JSON.parse(res.body);
+        }
+        catch {
+            body = {};
+        }
+        if (res.status === 401) {
+            this.health?.record('x-api', { ok: false, status: 401, latencyMs: res.latencyMs });
+            throw new XApiError('unauthorized', 'X answered 401: the login was revoked or expired — run `dexterm x login`', 401);
+        }
+        if (res.status === 429) {
+            const reset = Number(res.headers['x-rate-limit-reset']);
+            const resetAt = Number.isFinite(reset) && reset > 0 ? reset * 1000 : this.clock.now() + 15 * 60_000;
+            if (this.limiter)
+                this.limiter.pause(X_BUCKET, Math.max(1000, Math.min(resetAt - this.clock.now(), 15 * 60_000)));
+            this.health?.record('x-api', { ok: false, status: 429, latencyMs: res.latencyMs });
+            throw new XApiError('rate-limited', `${key}: X rate limit (resets ${new Date(resetAt).toISOString()})`, 429, resetAt);
+        }
+        if (res.status === 403) {
+            this.health?.record('x-api', { ok: false, status: 403, latencyMs: res.latencyMs, error: String(body.reason ?? body.title ?? '') });
+            if (body.reason === 'client-not-enrolled' || /enrollment|attached to a Project/i.test(String(body.detail ?? '')))
+                throw new XApiError('not-enrolled', `${key}: your X app's tier cannot read this endpoint (Free tier has no search / list timelines; see docs: Login with X)`, 403);
+            throw new XApiError('forbidden', `${key}: X answered 403 ${String(body.title ?? '')}`.trim(), 403);
+        }
+        if (res.status < 200 || res.status >= 300) {
+            this.health?.record('x-api', { ok: false, status: res.status, latencyMs: res.latencyMs });
+            throw new XApiError('http', `${key}: X answered ${res.status} ${String(body.title ?? body.detail ?? '')}`.trim(), res.status);
+        }
+        this.health?.record('x-api', { ok: true, status: res.status, latencyMs: res.latencyMs });
+        return { data: body, res };
+    }
+    cacheKey(key, params) {
+        return `${key}:${new URLSearchParams(params).toString()}`;
+    }
+    parsePage(env, fetchedAt, cached) {
+        const users = new Map();
+        for (const u of env.includes?.users ?? []) {
+            const r = u;
+            if (typeof r.id === 'string' && typeof r.username === 'string')
+                users.set(r.id, { id: r.id, username: r.username, name: typeof r.name === 'string' ? r.name : null, createdAt: typeof r.created_at === 'string' ? Date.parse(r.created_at) || null : null });
+        }
+        const tweets = [];
+        for (const t of env.data ?? []) {
+            const r = t;
+            if (typeof r.id !== 'string' || typeof r.text !== 'string')
+                continue;
+            const m = r.public_metrics ?? {};
+            const n = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+            tweets.push({ id: r.id, text: r.text, authorId: typeof r.author_id === 'string' ? r.author_id : '?', createdAt: typeof r.created_at === 'string' ? Date.parse(r.created_at) || fetchedAt : fetchedAt, lang: typeof r.lang === 'string' ? r.lang : null, metrics: { likes: n(m.like_count), reposts: n(m.retweet_count), replies: n(m.reply_count), views: typeof m.impression_count === 'number' ? m.impression_count : null } });
+        }
+        return { tweets, users, newestId: typeof env.meta?.newest_id === 'string' ? env.meta.newest_id : (tweets[0]?.id ?? null), fetchedAt, cached };
+    }
+    async page(key, path, params) {
+        const ck = this.cacheKey(key, params);
+        const hit = this.cache?.get(X_QUERY_NS, ck);
+        if (hit && !hit.stale) {
+            this.onRequest?.({ endpoint: key, status: 200, latencyMs: 0, cached: true });
+            return this.parsePage(hit.value, hit.fetchedAt, true);
+        }
+        const { data } = await this.get(key, path, params);
+        const fetchedAt = this.clock.now();
+        this.cache?.set(X_QUERY_NS, ck, data, { ttlMs: this.queryTtlMs, fetchedAt });
+        const page = this.parsePage(data, fetchedAt, false);
+        this.spend?.record(page.tweets.map((t) => t.id), 0);
+        return page;
+    }
+    async me() {
+        const { data } = await this.get('me', '/2/users/me', { 'user.fields': X_USER_FIELDS });
+        const d = data.data;
+        if (!d || typeof d.id !== 'string' || typeof d.username !== 'string')
+            throw new XApiError('http', 'users/me answered without a user');
+        this.spend?.record([], 1);
+        return { id: d.id, username: d.username, name: typeof d.name === 'string' ? d.name : null, createdAt: typeof d.created_at === 'string' ? Date.parse(d.created_at) || null : null };
+    }
+    /**
+     * search/recent. `query` is built by the caller from mints/handles/symbols (never from post text);
+     * `-is:retweet -is:reply` are appended so reposts/replies are never billed.
+     */
+    searchRecent(query, opts = {}) {
+        const q = /-is:retweet/.test(query) ? query : `${query} -is:retweet -is:reply`;
+        const params = { query: q.slice(0, 512), max_results: String(Math.max(10, Math.min(X_SEARCH_MAX, opts.maxResults ?? 50))), 'tweet.fields': X_TWEET_FIELDS, expansions: 'author_id', 'user.fields': X_USER_FIELDS };
+        if (opts.sinceId)
+            params.since_id = opts.sinceId;
+        return this.page('search', '/2/tweets/search/recent', params);
+    }
+    listTweets(listId, opts = {}) {
+        if (!/^\d{1,30}$/.test(listId))
+            return Promise.reject(new XApiError('http', 'list id must be numeric'));
+        return this.page('list-tweets', `/2/lists/${listId}/tweets`, { max_results: String(Math.max(1, Math.min(100, opts.maxResults ?? 50))), 'tweet.fields': X_TWEET_FIELDS, expansions: 'author_id', 'user.fields': X_USER_FIELDS });
+    }
+    async ownedLists(userId) {
+        if (!/^\d{1,30}$/.test(userId))
+            throw new XApiError('http', 'user id must be numeric');
+        const { data } = await this.get('owned-lists', `/2/users/${userId}/owned_lists`, { 'list.fields': 'member_count,name', max_results: '100' });
+        return (data.data ?? []).filter((l) => typeof l.id === 'string' && typeof l.name === 'string').map((l) => ({ id: l.id, name: l.name, memberCount: typeof l.member_count === 'number' ? l.member_count : null }));
+    }
+    async listMembers(listId) {
+        if (!/^\d{1,30}$/.test(listId))
+            throw new XApiError('http', 'list id must be numeric');
+        const { data } = await this.get('list-members', `/2/lists/${listId}/members`, { 'user.fields': X_USER_FIELDS, max_results: '100' });
+        const out = (data.data ?? []).filter((u) => typeof u.id === 'string' && typeof u.username === 'string').map((u) => ({ id: u.id, username: u.username, name: typeof u.name === 'string' ? u.name : null, createdAt: typeof u.created_at === 'string' ? Date.parse(u.created_at) || null : null }));
+        this.spend?.record([], out.length);
+        return out;
+    }
+}
+/** Build a per-token search query from RESOLVED facts (symbol, mint, project handle), never from post text. */
+export function tokenQuery(opts) {
+    const parts = [];
+    const sym = opts.symbol.replace(/[^A-Za-z0-9_]/g, '');
+    if (sym.length >= 2)
+        parts.push(`$${sym}`);
+    if (/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(opts.mint))
+        parts.push(opts.mint);
+    const h = (opts.handle ?? '').replace(/^@/, '');
+    if (/^[A-Za-z0-9_]{1,15}$/.test(h))
+        parts.push(`from:${h}`);
+    return `(${parts.join(' OR ')}) -is:retweet -is:reply`;
+}
+/** `from:` query for up to 20 handles (X caps queries at 512 chars on Basic/Pro). */
+export function handlesQuery(handles) {
+    const hs = handles.filter((h) => /^[A-Za-z0-9_]{1,15}$/.test(h)).slice(0, 20);
+    return `(${hs.map((h) => `from:${h}`).join(' OR ')}) -is:retweet -is:reply`;
+}
+/** Tweet → RawPost for the social feed's ingest (which firewalls the text). `mints` are the CALLER's resolution. */
+export function tweetToRaw(t, users, opts) {
+    const u = users.get(t.authorId);
+    const handle = u ? `@${u.username}` : `@user${t.authorId.slice(-4)}`;
+    return {
+        id: `x:${t.id}`,
+        t: t.createdAt,
+        platform: 'x',
+        author: { id: t.authorId, handle, tier: 'none', createdAt: u?.createdAt ?? null },
+        text: t.text,
+        url: u ? `https://x.com/${u.username}/status/${t.id}` : `https://x.com/i/status/${t.id}`,
+        lang: t.lang,
+        metrics: t.metrics,
+        mints: opts.mints,
+        source: 'x-api',
+        fetchedAt: opts.fetchedAt,
+    };
+}

package/dist/packages/data/src/x/budget.js

@@ -0,0 +1,66 @@
+// @dexterm/data — the X spend meter (task-1357; INTEGRATIONS-DESIGN §4/§6). X bills the DEVELOPER account
+// per post read ($0.005) and per user read ($0.01), deduplicated per UTC day — and with Login with X each
+// dexterm user IS the developer of their own app, so this is the user's own money. The meter keeps a per-day
+// estimate in the shared cache DB, counts a post only the first time its id is seen in a UTC day (24 h local
+// dedup table), and hard-stops reads at the daily budget (default $10, `DEXTERM_X_DAILY_USD`). The numbers are
+// ESTIMATES from the published list prices; the X console is the bill.
+export const X_USD_PER_POST = 0.005;
+export const X_USD_PER_USER_READ = 0.01;
+export const X_DEFAULT_DAILY_USD = 10;
+export const X_BUDGET_NS = 'x:budget';
+export const X_SEEN_NS = 'x:seen';
+const DAY_MS = 86_400_000;
+export function utcDayKey(now) {
+    return new Date(now).toISOString().slice(0, 10);
+}
+export function dailyBudgetFrom(env = process.env) {
+    const v = Number(env.DEXTERM_X_DAILY_USD);
+    return Number.isFinite(v) && v >= 0 ? v : X_DEFAULT_DAILY_USD;
+}
+export class XSpendMeter {
+    cache;
+    now;
+    budgetUsd;
+    constructor(opts) {
+        this.cache = opts.cache;
+        this.now = opts.now ?? (() => Date.now());
+        this.budgetUsd = opts.budgetUsd ?? dailyBudgetFrom(opts.env ?? process.env);
+    }
+    read(day) {
+        return this.cache.get(X_BUDGET_NS, day)?.value ?? { day, requests: 0, posts: 0, dedupedPosts: 0, userReads: 0, usd: 0 };
+    }
+    write(d) {
+        this.cache.set(X_BUDGET_NS, d.day, d, { ttlMs: 3 * DAY_MS });
+    }
+    status() {
+        const now = this.now();
+        const d = this.read(utcDayKey(now));
+        const pct = this.budgetUsd > 0 ? d.usd / this.budgetUsd : 1;
+        const dayStart = Date.UTC(new Date(now).getUTCFullYear(), new Date(now).getUTCMonth(), new Date(now).getUTCDate());
+        return { ...d, budgetUsd: this.budgetUsd, pct, level: pct >= 1 ? 'stop' : pct >= 0.8 ? 'warn' : 'ok', resetsAt: dayStart + DAY_MS };
+    }
+    /** True while another read is allowed (a zero budget means "never read X"). */
+    allow() { return this.status().level !== 'stop'; }
+    /** Record one request that returned `postIds` (new ids are billed) and `userReads` user objects. */
+    record(postIds, userReads = 0) {
+        const now = this.now();
+        const d = this.read(utcDayKey(now));
+        d.requests += 1;
+        let fresh = 0;
+        for (const id of postIds) {
+            if (this.cache.get(X_SEEN_NS, id)) {
+                d.dedupedPosts += 1;
+                continue;
+            }
+            this.cache.set(X_SEEN_NS, id, 1, { ttlMs: DAY_MS, fetchedAt: now });
+            fresh += 1;
+        }
+        d.posts += fresh;
+        d.userReads += userReads;
+        d.usd = Math.round((d.posts * X_USD_PER_POST + d.userReads * X_USD_PER_USER_READ) * 1000) / 1000;
+        this.write(d);
+        return d;
+    }
+    /** Drop stale `seen` rows (called by the poller once a minute; cheap). */
+    prune() { return this.cache.prune(0); }
+}

package/dist/packages/data/src/x/config.js

@@ -0,0 +1,49 @@
+// @dexterm/data — Login with X: constants, endpoints, local paths and secret redaction (task-1357, lane I-02;
+// INTEGRATIONS-DESIGN §3, research/task-1289/xlogin).
+//
+// Facts this encodes (docs.x.com, fetched 2026-10-09 by the spike):
+//   * authorize  https://x.com/i/oauth2/authorize   (response_type=code, client_id, redirect_uri, scope, state,
+//                code_challenge, code_challenge_method=S256); the code must be exchanged within 30 s
+//   * token      POST https://api.x.com/2/oauth2/token  (x-www-form-urlencoded; a Native App is a PUBLIC client:
+//                client_id in the body, no secret). Access tokens live 2 h; refresh needs `offline.access`
+//   * revoke     POST https://api.x.com/2/oauth2/revoke (token + client_id)
+//   * callback   must match EXACTLY and must be http://127.0.0.1 (not localhost) for a local app → FIXED port
+//   * rate limits are per USER for user-context tokens; pay-per-use credits bill the DEVELOPER account that owns
+//     the app — each dexterm user brings their OWN app (client id), so each user pays for their own reads.
+//
+// Every endpoint is injectable so tests run the whole flow against the loopback mock server (./mock-server.ts)
+// and never touch x.com. Nothing in this directory ever logs a token: `redactXSecrets()` is applied to every
+// error string that could reach a log, the screen or the health registry.
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** Fixed loopback port: X requires an exact-match callback URL, so the port is part of the app registration. */
+export const X_CALLBACK_PORT = 41287;
+export const X_CALLBACK_PATH = '/callback';
+/** Scopes dexterm asks for. Never any `.write` or `dm.*` — dexterm never posts, likes, follows or DMs. */
+export const X_SCOPES = ['tweet.read', 'users.read', 'list.read', 'offline.access'];
+export const X_FORBIDDEN_SCOPE_RE = /\.write$|^dm\./;
+export const X_LIVE_ENDPOINTS = {
+    authorize: 'https://x.com/i/oauth2/authorize',
+    token: 'https://api.x.com/2/oauth2/token',
+    revoke: 'https://api.x.com/2/oauth2/revoke',
+    api: 'https://api.x.com',
+};
+export function callbackUri(port = X_CALLBACK_PORT) {
+    return `http://127.0.0.1:${port}${X_CALLBACK_PATH}`;
+}
+/** `$DEXTERM_HOME/x` (default `~/.dexterm/x`): client id + tokens, mode 0700. */
+export function xDir(env = process.env) {
+    const home = env.DEXTERM_HOME && env.DEXTERM_HOME.trim() ? env.DEXTERM_HOME : join(homedir(), '.dexterm');
+    return join(home, 'x');
+}
+const BEARER_RE = /(bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi;
+const TOKEN_PARAM_RE = /((?:access_token|refresh_token|token|code|code_verifier|client_secret)=)[^&\s"'<>]+/gi;
+const TOKEN_JSON_RE = /("(?:access_token|refresh_token|token|code_verifier|client_secret)"\s*:\s*")[^"]*(")/gi;
+/** Strip bearer tokens, OAuth form fields and token-bearing JSON fields from any string. Safe on any input. */
+export function redactXSecrets(text) {
+    return String(text).replace(BEARER_RE, '$1REDACTED').replace(TOKEN_PARAM_RE, '$1REDACTED').replace(TOKEN_JSON_RE, '$1REDACTED$2');
+}
+/** A client id is one token of URL-safe characters (X ids are base64url-ish and end in `:1:ci`). */
+export function isPlausibleClientId(id) {
+    return /^[A-Za-z0-9._:~-]{8,128}$/.test(id);
+}

package/dist/packages/data/src/x/index.js

@@ -0,0 +1,10 @@
+// @dexterm/data — Login with X + the user-authorized X read adapter (task-1357, lane I-02).
+export * from "./config.js";
+export * from "./pkce.js";
+export * from "./token-store.js";
+export * from "./transport.js";
+export * from "./oauth.js";
+export * from "./budget.js";
+export * from "./api.js";
+export * from "./source.js";
+export * from "./mock-server.js";