opencandle 0.2.0 → 0.4.0

package/dist/onboarding/providers.js

@@ -0,0 +1,239 @@
+// Provider registry — single source of truth for OpenCandle's credentialed
+// third-party data providers. Every setup pathway iterates this registry:
+// first-run startup, the `/connect` command, the `tool_result` credential
+// interception handler, and the gap-note generator all read from here.
+//
+// Adding a new credentialed provider is a two-step change: add its `ProviderId`
+// to the literal union below, and add its descriptor to the `PROVIDERS` array.
+// The `satisfies` check ensures TypeScript fails the build if the union and
+// the array ever disagree.
+import { getConfig, loadFileConfig } from "../config.js";
+// Declaration order matters: picker display order, per-workflow prompt priority,
+// getProvidersByCategory/getProvidersByTier iteration order.
+export const PROVIDERS = [
+    {
+        id: "alpha_vantage",
+        displayName: "Alpha Vantage",
+        category: "fundamentals",
+        tier: "hard",
+        aliases: ["financials", "fundamentals", "company-financials", "alphavantage"],
+        signupUrl: "https://www.alphavantage.co/support/#api-key",
+        freeTier: true,
+        envVar: "ALPHA_VANTAGE_API_KEY",
+        configPath: ["providers", "alphaVantage", "apiKey"],
+        unlocks: [
+            "company fundamentals",
+            "income/balance/cashflow statements",
+            "DCF valuation",
+            "earnings history",
+        ],
+        fallbackDescription: null,
+        snoozeDurationDays: 7,
+        instructionsHint: "Free, about 30 seconds, signup opens in your browser",
+    },
+    {
+        id: "fred",
+        displayName: "FRED",
+        category: "macro",
+        tier: "hard",
+        aliases: ["economy", "macro", "economic-data", "st-louis-fed"],
+        signupUrl: "https://fredaccount.stlouisfed.org/apikeys",
+        freeTier: true,
+        envVar: "FRED_API_KEY",
+        configPath: ["providers", "fred", "apiKey"],
+        unlocks: [
+            "interest rates",
+            "inflation data",
+            "yield curve",
+            "economic indicators",
+        ],
+        fallbackDescription: null,
+        snoozeDurationDays: 7,
+        instructionsHint: "Free, about 30 seconds, requires a St. Louis Fed account",
+    },
+    {
+        id: "finnhub",
+        displayName: "Finnhub",
+        category: "news",
+        tier: "soft",
+        aliases: ["news", "company-news", "finnhub-news"],
+        signupUrl: "https://finnhub.io/register",
+        freeTier: true,
+        envVar: "FINNHUB_API_KEY",
+        configPath: ["providers", "finnhub", "apiKey"],
+        unlocks: [
+            "ticker-tagged company news",
+            "sentiment enrichment with a dedicated news source",
+        ],
+        // Finnhub is a soft enrichment source — sentiment-summary continues to work
+        // with Twitter/Reddit/web search when Finnhub is missing. The fallback is
+        // "the other sentiment sources still run".
+        fallbackDescription: "Other sentiment sources (Reddit, Twitter, web search) continue to work without Finnhub",
+        snoozeDurationDays: 7,
+        instructionsHint: "Free, about 30 seconds, signup opens in your browser",
+    },
+    {
+        id: "brave",
+        displayName: "Brave Search",
+        category: "web_search",
+        tier: "soft",
+        aliases: ["brave", "brave-search"],
+        signupUrl: "https://brave.com/search/api/",
+        freeTier: true,
+        envVar: "BRAVE_API_KEY",
+        configPath: ["providers", "brave", "apiKey"],
+        unlocks: [
+            "tier-2 web search with freshness control",
+            "independent search index outside of DuckDuckGo",
+        ],
+        fallbackDescription: "Web search continues to work via DuckDuckGo (free, no key needed, lower-quality freshness)",
+        snoozeDurationDays: 7,
+        instructionsHint: "Free tier available, signup opens in your browser",
+    },
+    {
+        id: "exa",
+        displayName: "Exa",
+        category: "web_search",
+        tier: "soft",
+        // Note: "search" is a multi-provider alias shared with Brave. The registry
+        // exposes it via resolveProviderFromArgument as a sub-picker case, not as a
+        // single-provider alias — so it intentionally does NOT appear in either
+        // provider's `aliases` array here. Keeping aliases unique-per-provider lets
+        // resolveProviderFromArgument cleanly distinguish the alias case from the
+        // sub-picker case.
+        aliases: ["exa", "exa-search"],
+        signupUrl: "https://dashboard.exa.ai/",
+        freeTier: false,
+        envVar: "EXA_API_KEY",
+        configPath: ["providers", "exa", "apiKey"],
+        unlocks: [
+            "tier-1 semantic web search",
+            "full article text and highlights",
+            "higher freshness accuracy than DuckDuckGo",
+        ],
+        fallbackDescription: "Exa search continues to work via the keyless Exa MCP endpoint, which has lower rate limits but similar quality",
+        snoozeDurationDays: 7,
+        instructionsHint: "Paid with free tier, signup opens in your browser",
+    },
+];
+// -----------------------------------------------------------------------------
+// Lookup helpers
+// -----------------------------------------------------------------------------
+// Lazy-built index — populated on first helper call so module import has no
+// side effects. The test `importing the registry does not read the filesystem`
+// relies on this.
+let providersById;
+function byId() {
+    if (!providersById) {
+        providersById = new Map(PROVIDERS.map((p) => [p.id, p]));
+    }
+    return providersById;
+}
+export function listAllProviders() {
+    return PROVIDERS;
+}
+export function getProvider(id) {
+    const found = byId().get(id);
+    if (!found) {
+        throw new Error(`Unknown provider id: "${id}"`);
+    }
+    return found;
+}
+export function getProvidersByCategory(category) {
+    return PROVIDERS.filter((p) => p.category === category);
+}
+export function getProvidersByTier(tier) {
+    return PROVIDERS.filter((p) => p.tier === tier);
+}
+// -----------------------------------------------------------------------------
+// Credential source helpers
+// -----------------------------------------------------------------------------
+function readConfigValueByPath(obj, path) {
+    let cursor = obj;
+    for (const segment of path) {
+        if (cursor && typeof cursor === "object" && segment in cursor) {
+            cursor = cursor[segment];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return typeof cursor === "string" && cursor.length > 0 ? cursor : undefined;
+}
+// Provider-id → `Config` field mapping. `Config` (in src/config.ts) is the
+// canonical env-or-file resolved shape that tool implementations already use.
+// `hasCredential` reads from `getConfig()` so that tests mocking `getConfig`
+// see a consistent view; `getCredentialSource` reads `process.env` +
+// `loadFileConfig` directly because it needs to distinguish env from file.
+const CONFIG_FIELD_BY_ID = {
+    alpha_vantage: "alphaVantageApiKey",
+    fred: "fredApiKey",
+    finnhub: "finnhubApiKey",
+    brave: "braveApiKey",
+    exa: "exaApiKey",
+};
+export function hasCredential(id) {
+    const field = CONFIG_FIELD_BY_ID[id];
+    const value = getConfig()[field];
+    return typeof value === "string" && value.length > 0;
+}
+export function getCredentialSource(id) {
+    return getCredential(id).source;
+}
+export function getCredential(id) {
+    const descriptor = getProvider(id);
+    const envValue = process.env[descriptor.envVar];
+    if (envValue && envValue.length > 0)
+        return { source: "env", value: envValue };
+    // Lazy file-config read — only invoked when env is absent.
+    const fileConfig = loadFileConfig();
+    const fileValue = readConfigValueByPath(fileConfig, descriptor.configPath);
+    if (fileValue)
+        return { source: "file", value: fileValue };
+    return { source: "absent" };
+}
+// -----------------------------------------------------------------------------
+// /connect argument resolution
+// -----------------------------------------------------------------------------
+export function resolveProviderFromArgument(arg) {
+    const needle = arg.trim().toLowerCase();
+    if (!needle)
+        return undefined;
+    // 1. Exact provider id match (case-insensitive).
+    for (const p of PROVIDERS) {
+        if (p.id === needle)
+            return p;
+    }
+    // 2. Exact alias match.
+    for (const p of PROVIDERS) {
+        if (p.aliases.includes(needle))
+            return p;
+    }
+    // 3. Category match: if the needle matches a category name, return the
+    //    providers in that category. One match → single descriptor. Multiple
+    //    matches → array (triggers the sub-picker in the /connect handler).
+    const categories = [
+        "fundamentals",
+        "macro",
+        "news",
+        "web_search",
+    ];
+    const normalizedCategory = needle.replace("-", "_");
+    if (categories.includes(normalizedCategory)) {
+        const group = getProvidersByCategory(normalizedCategory);
+        if (group.length === 1)
+            return group[0];
+        if (group.length > 1)
+            return group;
+    }
+    // 4. Special shared alias: "search" → both web_search providers.
+    if (needle === "search" || needle === "web" || needle === "web-search") {
+        const searchProviders = getProvidersByCategory("web_search");
+        if (searchProviders.length === 1)
+            return searchProviders[0];
+        if (searchProviders.length > 1)
+            return searchProviders;
+    }
+    return undefined;
+}
+//# sourceMappingURL=providers.js.map

package/dist/onboarding/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/onboarding/providers.ts"],"names":[],"mappings":"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"}

package/dist/onboarding/state.d.ts

@@ -1,8 +1,37 @@
-export declare const ONBOARDING_VERSION = 1;
+import type { ProviderId } from "./providers.js";
+export declare const ONBOARDING_VERSION = 2;
+export type ProviderOnboardingEntry = {
+    status: "completed";
+    lastPromptAt: string;
+} | {
+    status: "snoozed";
+    lastPromptAt: string;
+    snoozeUntil: string;
+} | {
+    status: "never_ask";
+    lastPromptAt: string;
+};
 export interface OnboardingState {
     version: number;
-    financeSetupStatus?: "dismissed" | "completed";
+    /** ISO 8601 timestamp the welcome message was first seeded, or undefined if never. */
+    welcomeShownAt?: string;
+    providers: Partial<Record<ProviderId, ProviderOnboardingEntry>>;
 }
 export declare function getDefaultOnboardingState(): OnboardingState;
 export declare function loadOnboardingState(path?: string): OnboardingState;
 export declare function saveOnboardingState(state: OnboardingState, path?: string): void;
+export declare function markProviderCompleted(state: OnboardingState, id: ProviderId): OnboardingState;
+export declare function markProviderSnoozed(state: OnboardingState, id: ProviderId, days: number): OnboardingState;
+export declare function markProviderNeverAsk(state: OnboardingState, id: ProviderId): OnboardingState;
+export declare function markWelcomeShown(state: OnboardingState): OnboardingState;
+export declare function getProviderEntry(state: OnboardingState, id: ProviderId): ProviderOnboardingEntry | undefined;
+export interface ShouldPromptOptions {
+    /**
+     * When true, treats a `completed` entry as eligible for re-prompt. This is
+     * how stale credentials (401 after a previously-connected key) get a fresh
+     * offer.
+     */
+    stale?: boolean;
+}
+export declare function shouldPrompt(state: OnboardingState, id: ProviderId, now: Date, options?: ShouldPromptOptions): boolean;
+export declare function shouldShowWelcome(state: OnboardingState, hasUI: boolean): boolean;

package/dist/onboarding/state.js

@@ -1,31 +1,159 @@
+// Onboarding state schema and pure helpers.
+//
+// Shape: one flag for the welcome message (`welcomeShownAt`) plus a partial
+// per-provider map with a proper discriminated union for status + snooze.
+//
+// All transition helpers are PURE — they return a new state object rather
+// than mutating. The caller is responsible for persisting via saveOnboardingState.
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { ensureParentDir, getOnboardingPath } from "../infra/opencandle-paths.js";
-export const ONBOARDING_VERSION = 1;
+export const ONBOARDING_VERSION = 2;
 export function getDefaultOnboardingState() {
-    return { version: ONBOARDING_VERSION };
+    return { version: ONBOARDING_VERSION, providers: {} };
+}
+// -----------------------------------------------------------------------------
+// Load / save
+// -----------------------------------------------------------------------------
+const STATUS_VALUES = new Set(["completed", "snoozed", "never_ask"]);
+function parseEntry(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const obj = raw;
+    const status = obj.status;
+    if (typeof status !== "string" || !STATUS_VALUES.has(status))
+        return undefined;
+    const lastPromptAt = obj.lastPromptAt;
+    if (typeof lastPromptAt !== "string")
+        return undefined;
+    if (status === "snoozed") {
+        const snoozeUntil = obj.snoozeUntil;
+        if (typeof snoozeUntil !== "string")
+            return undefined;
+        return { status: "snoozed", lastPromptAt, snoozeUntil };
+    }
+    if (status === "completed") {
+        return { status: "completed", lastPromptAt };
+    }
+    return { status: "never_ask", lastPromptAt };
+}
+function parseProvidersMap(raw) {
+    if (!raw || typeof raw !== "object")
+        return {};
+    const result = {};
+    for (const [key, value] of Object.entries(raw)) {
+        const entry = parseEntry(value);
+        if (entry)
+            result[key] = entry;
+    }
+    return result;
 }
 export function loadOnboardingState(path = getOnboardingPath()) {
     if (!existsSync(path)) {
         return getDefaultOnboardingState();
     }
+    let raw;
     try {
-        const parsed = JSON.parse(readFileSync(path, "utf-8"));
-        if (!parsed || typeof parsed !== "object") {
-            return getDefaultOnboardingState();
-        }
-        return {
-            version: typeof parsed.version === "number" ? parsed.version : ONBOARDING_VERSION,
-            financeSetupStatus: parsed.financeSetupStatus === "completed" || parsed.financeSetupStatus === "dismissed"
-                ? parsed.financeSetupStatus
-                : undefined,
-        };
+        raw = readFileSync(path, "utf-8");
     }
     catch {
         return getDefaultOnboardingState();
     }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return getDefaultOnboardingState();
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return getDefaultOnboardingState();
+    }
+    const obj = parsed;
+    const version = typeof obj.version === "number" ? obj.version : ONBOARDING_VERSION;
+    const welcomeShownAt = typeof obj.welcomeShownAt === "string" ? obj.welcomeShownAt : undefined;
+    const providers = parseProvidersMap(obj.providers);
+    return { version, welcomeShownAt, providers };
 }
 export function saveOnboardingState(state, path = getOnboardingPath()) {
     ensureParentDir(path);
-    writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, "utf-8");
+    // Strip undefined fields for cleaner on-disk output.
+    const serializable = {
+        version: state.version,
+        providers: state.providers,
+    };
+    if (state.welcomeShownAt !== undefined) {
+        serializable.welcomeShownAt = state.welcomeShownAt;
+    }
+    writeFileSync(path, `${JSON.stringify(serializable, null, 2)}\n`, "utf-8");
+}
+// -----------------------------------------------------------------------------
+// Pure transitions
+// -----------------------------------------------------------------------------
+function nowIso() {
+    return new Date().toISOString();
+}
+export function markProviderCompleted(state, id) {
+    return {
+        ...state,
+        providers: {
+            ...state.providers,
+            [id]: { status: "completed", lastPromptAt: nowIso() },
+        },
+    };
+}
+export function markProviderSnoozed(state, id, days) {
+    const now = new Date();
+    const snoozeUntil = new Date(now.getTime() + days * 24 * 3600 * 1000);
+    return {
+        ...state,
+        providers: {
+            ...state.providers,
+            [id]: {
+                status: "snoozed",
+                lastPromptAt: now.toISOString(),
+                snoozeUntil: snoozeUntil.toISOString(),
+            },
+        },
+    };
+}
+export function markProviderNeverAsk(state, id) {
+    return {
+        ...state,
+        providers: {
+            ...state.providers,
+            [id]: { status: "never_ask", lastPromptAt: nowIso() },
+        },
+    };
+}
+export function markWelcomeShown(state) {
+    return { ...state, welcomeShownAt: nowIso() };
+}
+// -----------------------------------------------------------------------------
+// Pure queries
+// -----------------------------------------------------------------------------
+export function getProviderEntry(state, id) {
+    return state.providers[id];
+}
+export function shouldPrompt(state, id, now, options = {}) {
+    const entry = state.providers[id];
+    if (!entry)
+        return true;
+    switch (entry.status) {
+        case "never_ask":
+            return false;
+        case "completed":
+            return options.stale === true;
+        case "snoozed": {
+            const until = Date.parse(entry.snoozeUntil);
+            if (Number.isNaN(until))
+                return true;
+            return now.getTime() >= until;
+        }
+    }
+}
+export function shouldShowWelcome(state, hasUI) {
+    if (!hasUI)
+        return false;
+    return state.welcomeShownAt === undefined;
 }
 //# sourceMappingURL=state.js.map

package/dist/onboarding/state.js.map

@@ -1 +1 @@
-{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/onboarding/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAElF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAOpC,MAAM,UAAU,yBAAyB;IACvC,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAI,GAAG,iBAAiB,EAAE;IAC5D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,yBAAyB,EAAE,CAAC;IACrC,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAoB,CAAC;QAC1E,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC1C,OAAO,yBAAyB,EAAE,CAAC;QACrC,CAAC;QACD,OAAO;YACL,OAAO,EAAE,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,kBAAkB;YACjF,kBAAkB,EAChB,MAAM,CAAC,kBAAkB,KAAK,WAAW,IAAI,MAAM,CAAC,kBAAkB,KAAK,WAAW;gBACpF,CAAC,CAAC,MAAM,CAAC,kBAAkB;gBAC3B,CAAC,CAAC,SAAS;SAChB,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,yBAAyB,EAAE,CAAC;IACrC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAsB,EAAE,IAAI,GAAG,iBAAiB,EAAE;IACpF,eAAe,CAAC,IAAI,CAAC,CAAC;IACtB,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACtE,CAAC"}
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/onboarding/state.ts"],"names":[],"mappings":"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"}

package/dist/onboarding/tool-helpers.d.ts

@@ -0,0 +1,34 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { type ProviderId } from "./providers.js";
+import { type CredentialRequiredReason } from "./tool-tags.js";
+export interface CredentialRequiredDetails {
+    credentialRequired: {
+        provider: ProviderId;
+        reason: CredentialRequiredReason;
+        httpStatus?: number;
+    };
+}
+/**
+ * Wrap a tool's provider-calling logic with a credential-check layer.
+ *
+ * Usage:
+ * ```
+ * async execute(_, args) {
+ *   return withCredentialCheck("alpha_vantage", async () => {
+ *     const apiKey = getConfig().alphaVantageApiKey!;
+ *     const result = await wrapProvider("alphavantage", () => getFinancials(args.symbol, apiKey));
+ *     // ... format success result ...
+ *     return { content: [...], details: [...] };
+ *   });
+ * }
+ * ```
+ *
+ * On missing credential (upfront): `fn` is NOT called. A tagged tool result
+ * is returned directly.
+ *
+ * On `ProviderCredentialError` thrown during `fn`: the error is caught and a
+ * tagged tool result is returned.
+ *
+ * Any other thrown value (plain Error, string, etc.) is re-thrown unchanged.
+ */
+export declare function withCredentialCheck<T>(providerId: ProviderId, fn: () => Promise<AgentToolResult<T>>): Promise<AgentToolResult<T> | AgentToolResult<CredentialRequiredDetails>>;

package/dist/onboarding/tool-helpers.js

@@ -0,0 +1,80 @@
+// Tool-boundary helpers for credentialed providers.
+//
+// `withCredentialCheck` is the single-entry helper that OpenCandle tools use
+// to wrap their provider calls. It centralizes:
+//   1. The upfront "credential missing" check via the registry.
+//   2. The catch-and-convert logic for `ProviderCredentialError` thrown from
+//      providers on 401/403 (stale credential after HTTP call).
+//   3. The tagged `[OPENCANDLE_CREDENTIAL_REQUIRED ...]` content emission that
+//      the Pi `tool_result` extension hook intercepts.
+//
+// Non-credential errors (network timeouts, parse errors, etc.) are re-thrown
+// unchanged so existing error handling in `wrapProvider` continues to work.
+import { ProviderCredentialError } from "../providers/provider-credential-error.js";
+import { getProvider, hasCredential } from "./providers.js";
+import { buildCredentialRequiredTag, } from "./tool-tags.js";
+function buildCredentialRequiredResult(provider, reason, httpStatus) {
+    const descriptor = getProvider(provider);
+    const tag = buildCredentialRequiredTag({
+        provider,
+        reason,
+        unlocks: descriptor.unlocks,
+        fallback: descriptor.fallbackDescription,
+        httpStatus,
+    });
+    // The second line is natural language describing what's missing. Users won't
+    // see it directly — the model sees it and uses the information to synthesize
+    // a gap note in its final answer. The tagged first line is the machine-
+    // readable signal the `tool_result` interception handler keys off of.
+    const narrative = reason === "missing"
+        ? `${descriptor.displayName} was not fetched for this request because no API key is configured. It unlocks ${descriptor.unlocks.join(", ")}.`
+        : `${descriptor.displayName} rejected the configured API key (HTTP ${httpStatus ?? "auth error"}). It may be expired or revoked.`;
+    return {
+        content: [{ type: "text", text: `${tag}\n\n${narrative}` }],
+        details: {
+            credentialRequired: {
+                provider,
+                reason,
+                ...(httpStatus !== undefined ? { httpStatus } : {}),
+            },
+        },
+    };
+}
+/**
+ * Wrap a tool's provider-calling logic with a credential-check layer.
+ *
+ * Usage:
+ * ```
+ * async execute(_, args) {
+ *   return withCredentialCheck("alpha_vantage", async () => {
+ *     const apiKey = getConfig().alphaVantageApiKey!;
+ *     const result = await wrapProvider("alphavantage", () => getFinancials(args.symbol, apiKey));
+ *     // ... format success result ...
+ *     return { content: [...], details: [...] };
+ *   });
+ * }
+ * ```
+ *
+ * On missing credential (upfront): `fn` is NOT called. A tagged tool result
+ * is returned directly.
+ *
+ * On `ProviderCredentialError` thrown during `fn`: the error is caught and a
+ * tagged tool result is returned.
+ *
+ * Any other thrown value (plain Error, string, etc.) is re-thrown unchanged.
+ */
+export async function withCredentialCheck(providerId, fn) {
+    if (!hasCredential(providerId)) {
+        return buildCredentialRequiredResult(providerId, "missing");
+    }
+    try {
+        return await fn();
+    }
+    catch (error) {
+        if (error instanceof ProviderCredentialError) {
+            return buildCredentialRequiredResult(error.provider, error.reason, error.httpStatus);
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=tool-helpers.js.map

package/dist/onboarding/tool-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-helpers.js","sourceRoot":"","sources":["../../src/onboarding/tool-helpers.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,6EAA6E;AAC7E,gDAAgD;AAChD,gEAAgE;AAChE,6EAA6E;AAC7E,gEAAgE;AAChE,+EAA+E;AAC/E,uDAAuD;AACvD,EAAE;AACF,6EAA6E;AAC7E,4EAA4E;AAG5E,OAAO,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,aAAa,EAAmB,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EACL,0BAA0B,GAE3B,MAAM,gBAAgB,CAAC;AAcxB,SAAS,6BAA6B,CACpC,QAAoB,EACpB,MAAgC,EAChC,UAAmB;IAEnB,MAAM,UAAU,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,0BAA0B,CAAC;QACrC,QAAQ;QACR,MAAM;QACN,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,QAAQ,EAAE,UAAU,CAAC,mBAAmB;QACxC,UAAU;KACX,CAAC,CAAC;IACH,6EAA6E;IAC7E,6EAA6E;IAC7E,wEAAwE;IACxE,sEAAsE;IACtE,MAAM,SAAS,GACb,MAAM,KAAK,SAAS;QAClB,CAAC,CAAC,GAAG,UAAU,CAAC,WAAW,kFAAkF,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QAC7I,CAAC,CAAC,GAAG,UAAU,CAAC,WAAW,0CAA0C,UAAU,IAAI,YAAY,kCAAkC,CAAC;IAEtI,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,SAAS,EAAE,EAAE,CAAC;QAC3D,OAAO,EAAE;YACP,kBAAkB,EAAE;gBAClB,QAAQ;gBACR,MAAM;gBACN,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACpD;SACF;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,UAAsB,EACtB,EAAqC;IAErC,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,OAAO,6BAA6B,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,uBAAuB,EAAE,CAAC;YAC7C,OAAO,6BAA6B,CAClC,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,UAAU,CACjB,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/onboarding/tool-tags.d.ts

@@ -0,0 +1,37 @@
+import type { ProviderId } from "./providers.js";
+export type CredentialRequiredReason = "missing" | "stale";
+export interface CredentialRequiredTagFields {
+    provider: ProviderId;
+    reason: CredentialRequiredReason;
+    unlocks: readonly string[];
+    fallback: string | null;
+    httpStatus?: number;
+}
+export interface SoftDegradedTagFields {
+    provider: ProviderId;
+    fallback: string;
+    remediation: string;
+}
+export interface SkippedTagFields {
+    provider: ProviderId;
+    reason: "credential_not_provided";
+    remediation: string;
+    silenced?: boolean;
+}
+export interface ConnectedTagFields {
+    provider: ProviderId;
+}
+export type ParsedTag = ({
+    kind: "credential_required";
+} & CredentialRequiredTagFields) | ({
+    kind: "soft_degraded";
+} & SoftDegradedTagFields) | ({
+    kind: "skipped";
+} & SkippedTagFields) | ({
+    kind: "connected";
+} & ConnectedTagFields);
+export declare function buildCredentialRequiredTag(fields: CredentialRequiredTagFields): string;
+export declare function buildSoftDegradedTag(fields: SoftDegradedTagFields): string;
+export declare function buildSkippedTag(fields: SkippedTagFields): string;
+export declare function buildConnectedTag(fields: ConnectedTagFields): string;
+export declare function parseToolTag(text: string): ParsedTag | undefined;