@sprid/cli 0.1.2

package/src/docs/help.mjs

@@ -0,0 +1,77 @@
+import { COMMAND_GROUPS, CLI_NOTES, COMMAND_EXAMPLES } from './commands.mjs';
+import { UsageError } from '../args.mjs';
+import { wrap } from '../format.mjs';
+
+export const HELP_TOPICS = {
+  environment: [
+    'SPRID_PAT: personal access token; overrides ~/.sprid/credentials.json.',
+    'SPRID_URL: API address; overrides the saved address. HTTPS except on loopback.',
+    'SPRID_APP_URL: browser app address; otherwise derived from the API address.',
+    'Workspace: --workspace/-w > .sprid/app.json workspaceId > saved choice > sole workspace > local workspace slug.',
+    'Local media can pin tokenEnv in sprid.config; that token is required when configured.',
+    'Never paste credentials into a command example or an agent conversation. Connect with --key <file>.',
+  ],
+  'exit-codes': [
+    '0: success.',
+    '1: runtime, authentication or API failure, or a declined review reply.',
+    '2: invalid usage or a required explicit choice (including public replies without --yes in scripts).',
+    'Local media, screenshot and release tools may propagate their own nonzero exit codes.',
+    '--json: one result on stdout; diagnostics on stderr. Failures carry ok: false and error. Local tools may return exitCode and output instead.',
+    'A failed mutation may have reached the server. Read its saved state before retrying; retain upload request IDs.',
+    'sprid mcp is a streaming protocol transport, not a one-document JSON command.',
+  ],
+};
+
+export const commandNames = () => [...new Set(COMMAND_GROUPS.flatMap(g => g.entries.map(e => e.command)))];
+
+export function commandEntries(command) {
+  const entries = COMMAND_GROUPS.flatMap(g => g.entries).filter(e => e.command === command);
+  // The local media namespace aliases the existing local post commands.
+  if (command === 'media') {
+    const local = COMMAND_GROUPS.find(g => g.title === 'Build your own media');
+    return [...entries.filter(e => !e.usage.includes('init|build')), ...local.entries.map(e => ({ ...e, command, usage: e.usage.replace('sprid post ', 'sprid media ') }))];
+  }
+  return entries;
+}
+
+export function subcommands(entry) {
+  const token = entry.usage.split(/\s+/)[2];
+  return token && /^[a-z][a-z0-9-]*(\|[a-z][a-z0-9-]*)*$/.test(token) ? token.split('|') : [];
+}
+
+// Suggestions never execute a corrected command, particularly a mutation.
+export function suggest(input, candidates) {
+  const distance = (a, b) => {
+    let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+      const next = [i];
+      for (let j = 1; j <= b.length; j++) next[j] = Math.min(next[j - 1] + 1, row[j] + 1, row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+      row = next;
+    }
+    return row[b.length];
+  };
+  return candidates.map(name => ({ name, distance: distance(input, name) }))
+    .filter(x => x.distance <= Math.min(2, Math.floor(input.length / 2)))
+    .sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name))[0]?.name;
+}
+
+export function getHelp(path = []) {
+  const [command, subcommand, ...extra] = path;
+  if (!command) return { commands: commandNames(), groups: COMMAND_GROUPS, examples: COMMAND_EXAMPLES, notes: CLI_NOTES, url: 'https://sprid.studio/docs/cli' };
+  if (Object.hasOwn(HELP_TOPICS, command) && !subcommand) return { topic: command, notes: HELP_TOPICS[command] };
+  let entries = commandEntries(command);
+  if (!entries.length) {
+    const match = suggest(command, commandNames());
+    throw new UsageError(`Unknown command "${command}".${match ? ` Did you mean "${match}"?` : ''} Run sprid help.`);
+  }
+  if (subcommand) entries = entries.filter(e => subcommands(e).includes(subcommand) || /^\[?</.test(e.usage.split(/\s+/)[2] ?? ''));
+  if (!entries.length || extra.length) throw new UsageError(`Unknown help topic "${path.join(' ')}". Run sprid help ${command}.`);
+  const examples = (COMMAND_EXAMPLES[command] ?? []).filter(example => !subcommand || example.startsWith(`sprid ${command} ${subcommand} `));
+  return { command, ...(subcommand ? { subcommand } : {}), entries, examples, notes: ['--help, -h: show help without running the command.', '--json: emit a machine-readable result.', '--workspace, -w <slug|id>: select a workspace for connected commands.'], url: 'https://sprid.studio/docs/cli' };
+}
+
+export function renderHelp(help, version) {
+  if (help.topic) return `sprid help ${help.topic}\n\n${help.notes.join('\n\n')}`;
+  if (help.entries) return `${help.entries.map(e => `${e.usage}\n  ${e.summary}`).join('\n\n')}${help.examples.length ? '\n\nExamples:\n  ' + help.examples.join('\n  ') : ''}\n\n${help.notes.join('\n')}\n\n${help.url}`;
+  return `sprid ${version} · the Sprid command line\n\nUsage: sprid <command> [options]\n\nStart here:\n  sprid login          Sign in through your browser\n  sprid status         See what needs you\n  sprid docs           Browse guides and references\n\nCommands:\n  ${wrap(help.commands.join('  '), 76).join('\n  ')}\n\nLearn more:\n  sprid help <command> [<subcommand>]\n  sprid help environment\n  sprid help exit-codes\n  sprid docs cli       Full installed command reference\n  sprid help --json    Machine-readable catalog\n\n${help.url}`;
+}

package/src/docs/index.d.mts

@@ -0,0 +1,18 @@
+import type { QueryOperation } from './queries.mjs';
+export interface QueryReference { topic: 'queries'; title: string; operations: QueryOperation[]; markdown: string; url: string; }
+export interface MetricReference { topic: 'metrics'; title: string; markdown: string; url: string; }
+export interface GuideSection { id: string; title: string; kind: 'requirements' | 'identifiers' | 'steps' | 'command' | 'verify' | 'troubleshooting' | 'sources' | 'detail'; markdown: string; }
+export interface Guide { topic: 'connect'; id: string; title: string; summary: string; command: string; url: string; sections: GuideSection[]; markdown: string; revision: string; }
+export interface ContentGuide { topic: 'content'; id: string; title: string; summary: string; url: string; markdown: string; revision: string; }
+export interface CommandGroup { title: string; entries: { command: string; usage: string; summary: string }[]; }
+export interface CommandReference { topic: 'cli'; title: string; groups: CommandGroup[]; notes: string[]; markdown: string; url: string; }
+export interface GuideIndex { topic: 'index'; title: string; guides: (Pick<Guide, 'id' | 'title' | 'summary' | 'url'> & { revision?: string })[]; }
+export function searchDocumentation(query: string): { id: string; title: string; url: string; read: string; excerpt: string; score: number }[];
+export const GUIDE_GROUPS: { title: string; slugs: string[] }[];
+export const COMMAND_GROUPS: CommandGroup[];
+export const CLI_NOTES: string[];
+export function getDocumentation(topic: 'cli'): CommandReference;
+export function getDocumentation(topic: undefined): GuideIndex;
+export function getDocumentation(topic: 'metrics'): MetricReference;
+export function getDocumentation(topic: string): Guide | ContentGuide | QueryReference | CommandReference | MetricReference;
+export function getDocumentation(topic?: string): Guide | ContentGuide | QueryReference | CommandReference | MetricReference | GuideIndex;

package/src/docs/index.mjs

@@ -0,0 +1,45 @@
+import { QUERY_OPERATIONS, renderQueryReference } from './queries.mjs';
+import { GUIDES, CONTENT_GUIDES, GUIDE_ALIASES, METRIC_EVIDENCE } from './guides.generated.mjs';
+import { COMMAND_GROUPS, CLI_NOTES, renderCommandReference } from './commands.mjs';
+export { GUIDE_GROUPS } from './guides.generated.mjs';
+export { COMMAND_GROUPS, CLI_NOTES } from './commands.mjs';
+
+/** Pure content lookup: shared by the website, REST, MCP and CLI. */
+export function getDocumentation(topic) {
+  if (topic === 'metrics') return { topic: 'metrics', title: 'Metric evidence', markdown: METRIC_EVIDENCE, url: 'https://sprid.studio/docs/metrics' };
+  if (!topic) return { topic: 'index', title: 'Sprid guides', guides: [
+    { id: 'cli', title: 'CLI reference', summary: 'Installed command syntax, options and shell completion.', url: 'https://sprid.studio/docs/cli' },
+    { id: 'queries', title: 'Query connected data', summary: 'Read-operation schemas and examples.', url: 'https://sprid.studio/docs/queries' },
+    { id: 'metrics', title: 'Metric evidence', summary: 'Metric definitions, units and coverage.', url: 'https://sprid.studio/docs/metrics' },
+    ...[...GUIDES, ...CONTENT_GUIDES].map(({ id, title, summary, url, revision }) => ({ id, title, summary, url, revision })),
+  ] };
+  if (topic === 'queries') return { topic: 'queries', title: 'Query connected data', operations: QUERY_OPERATIONS, markdown: renderQueryReference(), url: 'https://sprid.studio/docs/queries' };
+  if (topic === 'cli') return { topic: 'cli', title: 'CLI reference', groups: COMMAND_GROUPS, notes: CLI_NOTES, markdown: renderCommandReference(), url: 'https://sprid.studio/docs/cli' };
+  const id = Object.hasOwn(GUIDE_ALIASES, topic) ? GUIDE_ALIASES[topic] : topic;
+  const guide = GUIDES.find(guide => guide.id === id);
+  if (guide) return { topic: 'connect', ...guide };
+  const contentGuide = CONTENT_GUIDES.find(guide => guide.id === id);
+  if (contentGuide) return { topic: 'content', ...contentGuide };
+  throw new RangeError(`Unknown guide "${topic}". Run sprid docs to list guides.`);
+}
+
+/** Search the shipped content, never credentials, repositories or a remote index. */
+export function searchDocumentation(query) {
+  const terms = query.toLowerCase().trim().split(/\s+/).filter(Boolean);
+  if (!terms.length) return [];
+  const documents = getDocumentation().guides.map(guide => ({ ...guide, text: getDocumentation(guide.id).markdown, read: `sprid docs ${guide.id}` }));
+  documents.push(...COMMAND_GROUPS.flatMap(group => group.entries.map(entry => ({
+    id: `cli:${entry.usage}`, title: entry.usage, summary: entry.summary, text: entry.summary,
+    url: 'https://sprid.studio/docs/cli', read: `sprid help ${entry.command}`,
+  }))));
+  return documents.flatMap(document => {
+    const title = `${document.id} ${document.title}`.toLowerCase();
+    const text = `${document.summary} ${document.text}`.replace(/\s+/g, ' ');
+    const haystack = `${title} ${text}`.toLowerCase();
+    if (!terms.every(term => haystack.includes(term))) return [];
+    const score = terms.reduce((n, term) => n + (title.includes(term) ? 10 : 1), 0);
+    const at = Math.max(0, text.toLowerCase().indexOf(terms[0]) - 60);
+    return [{ id: document.id, title: document.title, url: document.url, read: document.read,
+      excerpt: `${at ? '…' : ''}${text.slice(at, at + 240)}${text.length > at + 240 ? '…' : ''}`, score }];
+  }).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+}

package/src/docs/queries.d.mts

@@ -0,0 +1,11 @@
+export interface QueryField {
+  type: string; description?: string; maxLength?: number; minimum?: number; maximum?: number;
+  enum?: string[]; pattern?: string; format?: string; items?: QueryField; maxItems?: number;
+  properties?: Record<string, QueryField>; required?: string[]; additionalProperties?: boolean | QueryField; maxProperties?: number;
+}
+export interface QueryOperation { source: string; operation: string; description: string; inputSchema: QueryField; example: Record<string, unknown>; identifiers?: string[]; }
+export interface QuerySource { source: string; title: string; identifiers: string[]; secrets: string[]; coverage: string; docs: string; stored?: boolean; }
+export const QUERY_SOURCES: Record<string, QuerySource>;
+export const QUERY_OPERATIONS: QueryOperation[];
+
+export function renderQueryReference(): string;

package/src/docs/queries.mjs

@@ -0,0 +1,77 @@
+// One operation catalogue for MCP discovery, CLI help, validation and the web.
+const str = (description, extra = {}) => ({ type: 'string', maxLength: 500, description, ...extra });
+const id = description => str(description, { pattern: '^[A-Za-z0-9_-]+$' });
+const integer = (description, maximum = 100, minimum = 1) => ({ type: 'integer', minimum, maximum, description });
+const choice = (description, values) => str(description, { enum: values });
+const array = (items, maxItems = 20) => ({ type: 'array', items, maxItems });
+const object = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+const date = description => str(description, { format: 'date', pattern: '^\\d{4}-\\d{2}-\\d{2}$' });
+const dates = { start: date('First calendar date, inclusive.'), end: date('Last boundary, exclusive. Provider date conventions are retained in the result.') };
+const limit = integer('Rows per page; continue with the returned next parameters.');
+const page = integer('One-based page.', 10000);
+const cursor = str('Opaque cursor from the previous result. Never a URL.', { maxLength: 2000 });
+const scalarMap = { type: 'object', additionalProperties: str('Provider-specific value.'), maxProperties: 20 };
+const chart = id('Chart name from RevenueCat documentation, such as revenue, mrr, trials or churn.');
+const filter = object({ name: id('Filter name from chart_options.'), values: array(str('Allowed filter value.')) }, ['name', 'values']);
+const sources = {
+  posthog: ['PostHog', ['posthogProjectId'], ['posthogApiKey'], 'Project-pinned analytics. SQL is HogQL; inspect instrumentation before interpreting events.', 'https://posthog.com/docs/api'],
+  gsc: ['Search Console', ['gscProperty'], ['gscServiceAccountJson'], 'Pinned Search Console property. Dates use Pacific time; anonymized queries and top-row limits affect coverage.', 'https://developers.google.com/webmaster-tools/v1/searchanalytics/query'],
+  cloudflare: ['Cloudflare', ['cloudflareAccountTag', 'websiteUrl'], ['cloudflareApiToken'], 'RUM is pinned to the saved account and website hostname. Beacon traffic is sampled and is not verified human traffic.', 'https://developers.cloudflare.com/analytics/graphql-api/'],
+  asc: ['App Store Connect', ['appStoreId'], ['ascIssuerId', 'ascKeyId', 'ascPrivateKey'], 'Pinned app. Reviews and existing analytics report definitions are read-only. No report request is created.', 'https://developer.apple.com/documentation/appstoreconnectapi/analytics'],
+  play: ['Google Play', ['playPackageName'], ['playServiceAccountJson'], 'Pinned package. Live reviews have provider history limits; exported acquisition rows require the saved Play export bucket.', 'https://developers.google.com/android-publisher/api-ref/rest/v3/reviews/list'],
+  revenuecat: ['RevenueCat', ['revenuecatProjectId'], ['revenuecatApiKey'], 'Pinned project. Discover chart options before selecting dimensions, filters or resolution; preserve returned measure units.', 'https://www.revenuecat.com/docs/api-v2/charts-and-metrics'],
+  stripe: ['Stripe', [], ['stripeApiKey'], 'Credential-scoped merchant account. Filter by price/customer as appropriate when several products share the account. Amounts retain currency and minor units; SQL/Stripe Analytics is not exposed.', 'https://docs.stripe.com/api'],
+  polar: ['Polar', ['polarOrganizationId'], ['polarApiKey'], 'Pinned organization. Product filters distinguish apps sold through the same organization.', 'https://polar.sh/docs/api-reference/metrics/get'],
+  lemonsqueezy: ['Lemon Squeezy', ['lemonSqueezyStoreId'], ['lemonSqueezyApiKey'], 'Pinned store. Product/variant filters distinguish apps in the same store. Preserve provider amounts and currencies.', 'https://docs.lemonsqueezy.com/api'],
+  paddle: ['Paddle', [], ['paddleApiKey'], 'Credential-scoped merchant account, with sandbox/live from the profile. Dates filter billed or created time as described; monetary values are minor-unit strings.', 'https://developer.paddle.com/api-reference/overview'],
+};
+export const QUERY_SOURCES = Object.fromEntries(Object.entries(sources).map(([source, [title, identifiers, secrets, coverage, docs]]) => [source, { source, title, identifiers, secrets, coverage, docs }]));
+for (const source of ['instagram', 'tiktok', 'youtube', 'facebook', 'linkedin', 'x']) QUERY_SOURCES[source] = {
+  source, title: ({ instagram: 'Instagram', tiktok: 'TikTok', youtube: 'YouTube', facebook: 'Facebook', linkedin: 'LinkedIn', x: 'X' })[source],
+  identifiers: [], secrets: [], stored: true,
+  coverage: 'Queries Sprid’s stored publishes, metric snapshots and inbox for the linked content account. No live platform sync or paid API read. Missing metrics are unmeasured; this does not expose the platform’s entire API.',
+  docs: 'https://sprid.studio/docs/queries',
+};
+export const QUERY_OPERATIONS = [];
+const op = (source, operation, description, properties, required, example, extra = {}) => QUERY_OPERATIONS.push({ source, operation, description, inputSchema: object(properties, required), example, ...extra });
+op('posthog', 'query', 'Run a custom read-only HogQL query for cohorts, ordered funnels, activation or retention.', { query: str('SELECT/WITH HogQL. Use explicit dates, identity and exclusions.', { maxLength: 20000 }) }, ['query'], { query: "SELECT event, count() FROM events WHERE timestamp >= '2026-08-01' AND timestamp < '2026-09-01' GROUP BY event LIMIT 100" });
+for (const operation of ['events', 'properties']) op('posthog', operation, `Discover ${operation === 'events' ? 'event' : 'property'} definitions before constructing a query.`, { ...(operation === 'events' ? { names: array(str('Exact event name.')) } : { search: str('Property name search.') }), limit, offset: integer('Zero-based offset.', 100000, 0) }, [], { limit: 50 });
+op('gsc', 'search', 'Query search performance by dimensions and filters, including page/market/keyword comparisons.', {
+  ...dates, dimensions: array(choice('Grouping dimension.', ['date', 'query', 'page', 'country', 'device', 'searchAppearance'])),
+  filters: array(object({ dimension: choice('Filtered dimension.', ['query', 'page', 'country', 'device', 'searchAppearance']), operator: choice('Match operator.', ['equals', 'notEquals', 'contains', 'notContains', 'includingRegex', 'excludingRegex']), expression: str('Filter expression.', { maxLength: 2000 }) }, ['dimension', 'operator', 'expression'])),
+  type: choice('Search type.', ['web', 'image', 'video', 'news', 'discover', 'googleNews']), dataState: choice('Final or preliminary data.', ['final', 'all']), limit: integer('Rows per page.', 25000), startRow: integer('Zero-based pagination offset.', 1000000, 0),
+}, ['start', 'end'], { start: '2026-08-01', end: '2026-09-01', dimensions: ['page', 'country'], limit: 1000 });
+op('cloudflare', 'rum', 'Group website beacon traffic by date, page, referrer or country.', { ...dates, dimensions: array(choice('RUM dimension.', ['date', 'requestPath', 'refererHost', 'countryName']), 4), path: str('Exact request path.'), country: str('Exact countryName.'), referrer: str('Exact refererHost.'), limit: integer('Maximum groups.', 1000) }, ['start', 'end'], { start: '2026-08-01', end: '2026-09-01', dimensions: ['requestPath', 'countryName'], limit: 100 });
+op('cloudflare', 'http', 'Read daily zone requests, page views and country totals. Includes bots; no silent RUM fallback.', dates, ['start', 'end'], { start: '2026-08-01', end: '2026-09-01' }, { identifiers: ['cloudflareZoneId'] });
+op('asc', 'reviews', 'Read app reviews by rating, territory and response status.', { rating: integer('Exact star rating.', 5), territory: id('Three-letter App Store territory.'), existsPublishedResponse: { type: 'boolean', description: 'Whether a published developer response exists.' }, sort: choice('Ordering.', ['createdDate', '-createdDate', 'rating', '-rating']), limit: integer('Reviews per page.', 200), cursor }, [], { rating: 2, limit: 100 });
+op('asc', 'versions', 'Inspect App Store version and release-state records for this app.', { limit: integer('Versions per page.', 200), cursor }, [], { limit: 50 });
+op('asc', 'reports', 'List existing analytics requests and their report names. Does not enable report generation.', {}, [], {});
+op('asc', 'report_rows', 'Read an existing named daily report with its original columns, date window and exact-value filters.', { ...dates, report: str('Exact report name returned by reports.'), filters: scalarMap, limit: integer('Maximum matching rows.', 1000), offset: integer('Matching-row offset.', 100000, 0) }, ['start', 'end', 'report'], { start: '2026-08-01', end: '2026-09-01', report: 'App Downloads Standard', limit: 500 });
+op('play', 'reviews', 'Read the app’s live review page; use stored reviews for older collected history.', { translationLanguage: str('Optional translation language, such as en.'), limit, cursor }, [], { limit: 100 });
+op('play', 'report_rows', 'Read package-scoped monthly acquisition exports with original column names and exact-value filters.', { ...dates, dimension: choice('Install export breakdown.', ['overview', 'country', 'device', 'app_version', 'android_version', 'language', 'carrier']), filters: scalarMap, limit: integer('Maximum matching rows.', 1000), offset: integer('Matching-row offset.', 100000, 0) }, ['start', 'end', 'dimension'], { start: '2026-08-01', end: '2026-09-01', dimension: 'country', limit: 500 }, { identifiers: ['playPackageName', 'playExportBucket'] });
+op('revenuecat', 'chart_options', 'Discover available resolutions, segments, filters and selectors for a chart.', { chart }, ['chart'], { chart: 'revenue' });
+op('revenuecat', 'revenue', 'Read the authoritative RevenueCat project revenue total for an explicit period.', { ...dates, currency: str('Requested reporting currency.', { pattern: '^[A-Z]{3}$' }), revenue_type: choice('Revenue basis.', ['revenue', 'revenue_net_of_taxes', 'proceeds']) }, ['start', 'end'], { start: '2026-08-01', end: '2026-09-01', currency: 'USD', revenue_type: 'revenue' });
+op('revenuecat', 'chart', 'Query a chart with provider-supported segmentation and filters; returns original measures.', { chart, ...dates, resolution: str('Resolution ID from chart_options, not a guessed day/week label.'), segment: id('Segment from chart_options.'), filters: array(filter), selectors: scalarMap, currency: str('Currency code.', { pattern: '^[A-Z]{3}$' }), limit_num_segments: integer('Top segments; provider may combine the remainder as Other.', 100) }, ['chart', 'start', 'end', 'resolution'], { chart: 'revenue', start: '2026-08-01', end: '2026-09-01', resolution: '0' });
+op('revenuecat', 'subscriptions', 'Inspect a customer’s subscriptions within the bound RevenueCat project.', { customer: str('RevenueCat customer ID; preserve the app’s verified identity mapping.', { maxLength: 150 }), environment: choice('Defaults to production. Keep sandbox separate from paid customer evidence.', ['production', 'sandbox']), limit, cursor }, ['customer'], { customer: 'example-customer', limit: 100 });
+const stripeFields = { ...dates, customer: id('Stripe customer ID.'), limit, cursor };
+op('stripe', 'subscriptions', 'Read subscriptions, status and lifecycle dates, optionally filtered by price/customer. Dates filter creation, not cancellation.', { ...stripeFields, status: choice('Subscription status.', ['all', 'active', 'trialing', 'past_due', 'unpaid', 'canceled', 'incomplete', 'incomplete_expired', 'paused']), price: id('Stripe price ID for the app or offer.') }, [], { status: 'trialing', limit: 100 });
+op('stripe', 'charges', 'Read charge outcomes, refunds and amounts by creation window or customer.', stripeFields, [], { start: '2026-08-01', end: '2026-09-01', limit: 100 });
+op('polar', 'metrics', 'Query metric history filtered by product, customer or billing type.', { ...dates, interval: choice('Bucket interval.', ['hour', 'day', 'week', 'month', 'year']), product_id: id('Polar product ID.'), customer_id: id('Polar customer ID.'), billing_type: choice('Billing type.', ['one_time', 'recurring']), metrics: array(id('Metric slug from the response metadata.')) }, ['start', 'end'], { start: '2026-08-01', end: '2026-09-01', interval: 'day', metrics: ['revenue', 'active_subscriptions'] });
+for (const operation of ['orders', 'subscriptions']) op('polar', operation, `Read ${operation} for the bound organization with product/customer filters.`, { product_id: id('Polar product ID.'), customer_id: id('Polar customer ID.'), limit, page }, [], { limit: 100, page: 1 });
+for (const operation of ['orders', 'subscriptions']) op('lemonsqueezy', operation, `Read ${operation} from the saved store with supported product filters.`, { ...(operation === 'subscriptions' ? { product_id: id('Product ID.'), variant_id: id('Variant ID.'), status: str('Subscription status.') } : { order_number: integer('Order number.', 1000000000) }), limit, page }, [], { limit: 100, page: 1 });
+op('lemonsqueezy', 'subscription-invoices', 'Read initial, renewal and update invoices from the saved store. Initial invoices duplicate initial orders; preserve billing_reason when calculating revenue.', { subscription_id: id('Subscription ID.'), status: str('Invoice status.'), refunded: { type: 'boolean', description: 'Filter refund state.' }, limit, page }, [], { limit: 100, page: 1 });
+op('paddle', 'transactions', 'Read billed transactions by time, status, customer or subscription.', { ...dates, status: array(choice('Status.', ['draft', 'ready', 'billed', 'paid', 'completed', 'canceled', 'past_due']), 7), customer_id: id('Paddle customer ID.'), subscription_id: id('Paddle subscription ID.'), limit, cursor }, [], { start: '2026-08-01', end: '2026-09-01', status: ['completed'], limit: 100 });
+op('paddle', 'subscriptions', 'Read subscription lifecycles by status or price; optional creation dates filter each returned page locally.', { ...dates, status: array(choice('Status.', ['active', 'canceled', 'past_due', 'paused', 'trialing']), 5), customer_id: id('Paddle customer ID.'), price_id: id('Paddle price ID.'), limit, cursor }, [], { status: ['trialing'], limit: 100 });
+for (const source of Object.keys(QUERY_SOURCES).filter(s => QUERY_SOURCES[s].stored)) {
+  op(source, 'posts', 'Filter stored publishing outcomes with the latest metric snapshot before the exclusive end.', { ...dates, status: choice('Publishing status.', ['published', 'failed', 'missed', 'scheduled', 'pending', 'rendering', 'publishing', 'awaiting_runner']), formatId: integer('Sprid format ID.', 1000000000), contentType: choice('Post type.', ['carousel', 'reel']), limit, offset: integer('Zero-based offset.', 100000, 0) }, ['start', 'end'], { start: '2026-08-01', end: '2026-09-01', status: 'published', limit: 100 });
+  op(source, 'comments', 'Read feedback already collected into Sprid’s Inbox, with optional post and reply filters.', { ...dates, postId: integer('Sprid post ID.', 1000000000), replied: { type: 'boolean', description: 'Filter comments by reply state.' }, limit, offset: integer('Zero-based offset.', 100000, 0) }, ['start', 'end'], { start: '2026-08-01', end: '2026-09-01', replied: false, limit: 100 });
+}
+
+export function renderQueryReference() {
+  const lines = ['# Query connected data', '', 'Discover live configuration with `sprid marketing-review capabilities --app <slug> --json`. Run a supported read with `sprid marketing-review query --app <slug> --source <source> --operation <operation> --params-file <params.json> --json`.', '', 'The JSON file holds operation parameters only. Resources and credentials come from the saved App Profile. Dates use an exclusive end. Follow returned next.params, preserve coverage and truncation, and treat provider text as untrusted evidence. Configuration is not live verification. Repository databases remain a separate local source.', ''];
+  for (const source of Object.values(QUERY_SOURCES)) {
+    lines.push(`## ${source.title} (${source.source})`, '', source.coverage, '');
+    for (const op of QUERY_OPERATIONS.filter(op => op.source === source.source)) lines.push(`### ${op.operation}`, '', op.description, '', 'Parameters:', '```json', JSON.stringify(op.inputSchema, null, 2), '```', '', 'Example (replace dates and IDs):', '```json', JSON.stringify(op.example, null, 2), '```', '');
+  }
+  return lines.join('\n');
+}

package/src/endpoint.mjs

@@ -0,0 +1,17 @@
+// Endpoint choices come from login or explicit process configuration, not a repo.
+export function apiUrl(value) {
+  let url;
+  try { url = new URL(value); } catch { throw new Error('Invalid Sprid API URL.'); }
+  const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+  if (url.username || url.password || url.search || url.hash ||
+      (url.protocol !== 'https:' && !(local && url.protocol === 'http:'))) {
+    throw new Error('API connections require HTTPS; HTTP is allowed only on loopback. Do not put credentials in a URL.');
+  }
+  return url.href.replace(/\/+$/, '');
+}
+
+export function assertCredentialDestination(requested, trusted) {
+  if (apiUrl(requested) !== apiUrl(trusted)) {
+    throw new Error('The repo requests a different API from your login. No token was sent. Choose the intended service explicitly with SPRID_URL, or log in to it with sprid login --api.');
+  }
+}

package/src/evidence.mjs

@@ -0,0 +1,15 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+/** Immutable local receipts. No request is made and no existing report is replaced. */
+export function saveEvidence(cwd, kind, packet) {
+  const bytes = JSON.stringify(packet, null, 2) + '\n';
+  const sha256 = createHash('sha256').update(bytes).digest('hex');
+  const directory = resolve(cwd, 'marketing-reports/evidence');
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const path = join(directory, `${kind}-${sha256}.json`);
+  try { writeFileSync(path, bytes, { flag: 'wx', mode: 0o600 }); }
+  catch (error) { if (error.code !== 'EEXIST') throw error; }
+  return { path, sha256 };
+}

package/src/format.mjs

@@ -0,0 +1,71 @@
+// Terminal output. Short, aligned, no colour when piped, ✓ ✗ – as the only
+// symbols.
+
+export const isTTY = () => Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+
+export const C = {
+  dim: (s) => (isTTY() ? `\x1b[2m${s}\x1b[0m` : s),
+  bold: (s) => (isTTY() ? `\x1b[1m${s}\x1b[0m` : s),
+  ok: (s) => (isTTY() ? `\x1b[32m${s}\x1b[0m` : s),
+  bad: (s) => (isTTY() ? `\x1b[31m${s}\x1b[0m` : s),
+  warn: (s) => (isTTY() ? `\x1b[33m${s}\x1b[0m` : s),
+};
+
+export const OK = "✓";
+export const BAD = "✗";
+export const NONE = "–";
+export const EXPIRING = "~";
+
+export function pad(s, n) {
+  s = String(s ?? "");
+  return s.length >= n ? s : s + " ".repeat(n - s.length);
+}
+
+/** Rows of cells → aligned lines. */
+export function table(rows, { indent = "  ", gap = 2 } = {}) {
+  const widths = [];
+  for (const r of rows) r.forEach((c, i) => (widths[i] = Math.max(widths[i] ?? 0, String(c ?? "").length)));
+  return rows
+    .map((r) => indent + r.map((c, i) => (i === r.length - 1 ? String(c ?? "") : pad(c, widths[i] + gap))).join("").trimEnd())
+    .join("\n");
+}
+
+export function healthMark(health) {
+  if (health === "ok") return OK;
+  if (health === "expiring") return EXPIRING;
+  if (health === "revoked" || health === "error") return BAD;
+  return NONE;
+}
+
+export function hhmm(iso) {
+  if (!iso) return "";
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return "";
+  return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+}
+
+const DAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+export function dayTime(iso) {
+  if (!iso) return "";
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return "";
+  return `${DAYS[d.getDay()]} ${hhmm(iso)}`;
+}
+
+/** Word-wrap at ~width, never breaking a token, so a URL in an error stays clickable. */
+export function wrap(text, width = 100) {
+  const out = [];
+  let line = "";
+  for (const word of String(text ?? "").split(/\s+/).filter(Boolean)) {
+    if (line && line.length + 1 + word.length > width) {
+      out.push(line);
+      line = word;
+    } else line = line ? `${line} ${word}` : word;
+  }
+  if (line) out.push(line);
+  return out;
+}
+
+export function capOf(n) {
+  return n == null ? "∞" : String(n);
+}

package/src/http.mjs

@@ -0,0 +1,117 @@
+// The one HTTP door. Every command talks to the same REST contract the web
+// app and the MCP server use; this wraps fetch with the bearer header, JSON
+// bodies, and an error that carries the server's own message.
+
+import { apiUrl as validateApiUrl } from './endpoint.mjs';
+import { compareVersions, stableVersion } from './updates.mjs';
+
+export class ApiError extends Error {
+  constructor(status, message, body) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.body = body;
+    this.exitCode = 1;
+  }
+}
+
+/**
+ * The server advertises the CLI floor it enforces on every response:
+ * `Sprid-Client-Supported` is advisory, `Sprid-Client-Minimum` is refused 426.
+ * Below the advisory floor we say so once and carry on - the work still runs.
+ */
+export function clientVersionNotice(headers, current) {
+  const supported = headers?.get?.("Sprid-Client-Supported");
+  if (!stableVersion(current) || !stableVersion(supported ?? "")) return null;
+  if (compareVersions(supported, current) <= 0) return null;
+  return `This Sprid CLI is ${current}; the server supports ${supported} and newer. Run \`sprid update\`.`;
+}
+
+/**
+ * The edge limiter's refusal (`error: "rate_limited"`) is rejected before the
+ * handler runs, so retrying it - a POST included - can never apply anything
+ * twice. Every other 429 (the publish cap, the AI spend
+ * cap) is a business refusal that waiting will not clear, and is not retried.
+ */
+export const RATE_LIMIT_RETRIES = 2;
+const MAX_RETRY_WAIT_MS = 60_000;
+
+export function rateLimitWaitMs(status, headers, data) {
+  if (status !== 429 || !data || typeof data !== "object" || data.error !== "rate_limited") return null;
+  // Refused for failed auth: the token is bad, and waiting will not fix it.
+  if (data.scope === "failed") return null;
+  const seconds = Number(headers?.get?.("Retry-After") ?? data.retryAfter);
+  const ms = Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : MAX_RETRY_WAIT_MS;
+  return Math.min(ms, MAX_RETRY_WAIT_MS);
+}
+
+export function makeClient({
+  apiUrl,
+  token,
+  fetchImpl = globalThis.fetch,
+  userAgent = "sprid",
+  version = null,
+  onNotice = null,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+}) {
+  apiUrl = validateApiUrl(apiUrl);
+  async function request(method, path, body, options = {}, attempt = 0) {
+    const { raw = false, timeoutMs = 30000 } = options;
+    const headers = { Accept: "application/json", "User-Agent": userAgent };
+    if (token) headers.Authorization = `Bearer ${token}`;
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+    let res;
+    try {
+      res = await fetchImpl(`${apiUrl}${path}`, {
+        method,
+        redirect: 'error',
+        signal: AbortSignal.timeout(timeoutMs),
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+      });
+    } catch (e) {
+      throw new ApiError(0, `Could not reach ${apiUrl}: ${e.message}`);
+    }
+    if (onNotice) {
+      const notice = clientVersionNotice(res.headers, version);
+      if (notice) onNotice(notice);
+    }
+    const text = await res.text();
+    let data = null;
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = text;
+      }
+    }
+    const waitMs = rateLimitWaitMs(res.status, res.headers, data);
+    if (waitMs !== null && attempt < RATE_LIMIT_RETRIES) {
+      if (onNotice) onNotice(`Sprid is rate limiting these requests. Waiting ${Math.ceil(waitMs / 1000)}s and retrying.`);
+      await sleep(waitMs);
+      return request(method, path, body, options, attempt + 1);
+    }
+    if (raw) return { status: res.status, data };
+    if (!res.ok) {
+      const msg =
+        (data && typeof data === "object" && (data.message || data.error)) ||
+        (typeof data === "string" && data.slice(0, 200)) ||
+        `${res.status} ${res.statusText}`;
+      throw new ApiError(res.status, describe(res.status, String(msg)), data);
+    }
+    return data;
+  }
+  return {
+    get: (path, options) => request("GET", path, undefined, options),
+    post: (path, body) => request("POST", path, body ?? {}),
+    patch: (path, body) => request("PATCH", path, body ?? {}),
+    del: (path) => request("DELETE", path),
+    raw: (method, path, body) => request(method, path, body, { raw: true }),
+  };
+}
+
+function describe(status, msg) {
+  if (status === 401) return `${msg}. The token was refused; run \`sprid login\` again.`;
+  if (status === 403) return `${msg}. This token cannot do that here.`;
+  return msg;
+}

package/src/pending.mjs

@@ -0,0 +1,27 @@
+// Browser grants are private CLI state, never repo files or agent output.
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
+import { credentialsPath } from "./creds.mjs";
+
+export function pendingGrant(ctx, identity) {
+  const key = createHash("sha256").update(identity).digest("hex");
+  const path = join(dirname(credentialsPath(ctx.env)), `pending-${key}.json`);
+  return {
+    read() {
+      try {
+        const data = JSON.parse(readFileSync(path, "utf8"));
+        if (data.expiresAt > Date.now()) return data;
+        rmSync(path, { force: true });
+      } catch (error) { if (error.code !== "ENOENT" && !(error instanceof SyntaxError)) throw error; }
+      return null;
+    },
+    write(data) {
+      mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+      const tmp = `${path}.${process.pid}.tmp`;
+      writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
+      renameSync(tmp, path);
+    },
+    clear() { rmSync(path, { force: true }); },
+  };
+}