fullstackgtm 0.10.0

package/dist/connectors/hubspotAuth.d.ts

@@ -0,0 +1,42 @@
+export declare const DEFAULT_OAUTH_SCOPES: string[];
+export declare const DEFAULT_LOOPBACK_PORT = 8763;
+export type HubspotTokenSet = {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: number;
+};
+export declare function validateHubspotToken(token: string, fetchImpl?: typeof fetch): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
+export declare function exchangeHubspotCode(options: {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    code: string;
+    fetchImpl?: typeof fetch;
+}): Promise<HubspotTokenSet>;
+export declare function refreshHubspotToken(options: {
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+    fetchImpl?: typeof fetch;
+}): Promise<HubspotTokenSet>;
+export type LoopbackLoginOptions = {
+    clientId: string;
+    clientSecret: string;
+    /** Must match a redirect URL registered on the HubSpot app: http://localhost:<port>/callback */
+    port?: number;
+    scopes?: string[];
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    /** Receives the authorize URL; default prints it and best-effort opens a browser. */
+    openUrl?: (url: string) => void | Promise<void>;
+    log?: (message: string) => void;
+};
+/**
+ * RFC 8252 loopback OAuth: serve one request on 127.0.0.1, send the user to
+ * the provider consent page, capture the code locally, exchange it directly.
+ */
+export declare function runHubspotLoopbackLogin(options: LoopbackLoginOptions): Promise<HubspotTokenSet>;
+export declare function openInBrowser(url: string): Promise<void>;

package/dist/connectors/hubspotAuth.js

@@ -0,0 +1,189 @@
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+/**
+ * HubSpot CLI authentication.
+ *
+ * Two paths, ordered by how little web they need:
+ * 1. Private app token — no OAuth at all; created once in HubSpot settings.
+ * 2. Bring-your-own-app OAuth with an RFC 8252 loopback redirect — the
+ *    browser is used for exactly one thing (the consent grant); the CLI
+ *    captures the code on 127.0.0.1 and performs the exchange itself.
+ *
+ * HubSpot does not support the device-authorization grant or PKCE-only
+ * public clients, so the loopback flow requires the user's own app client
+ * id/secret, which are kept locally for silent refresh.
+ */
+const HS_AUTH_URL = "https://app.hubspot.com/oauth/authorize";
+const HS_TOKEN_URL = "https://api.hubapi.com/oauth/v1/token";
+const HS_API_URL = "https://api.hubapi.com";
+export const DEFAULT_OAUTH_SCOPES = [
+    "crm.objects.deals.read",
+    "crm.objects.owners.read",
+    "crm.objects.companies.read",
+    "crm.objects.contacts.read",
+    "crm.objects.deals.write",
+];
+export const DEFAULT_LOOPBACK_PORT = 8763;
+/**
+ * OAuth error responses can echo request parameters (client_secret, code).
+ * Surface only the standard `error`/`error_description` fields, never the raw
+ * body, so secrets never reach logs.
+ */
+async function safeTokenError(response) {
+    let description;
+    try {
+        const data = await response.json();
+        description = data?.error_description ?? data?.error ?? data?.message;
+    }
+    catch {
+        // Non-JSON body — withhold it entirely.
+    }
+    return description
+        ? `${response.status} (${String(description).slice(0, 200)})`
+        : `HTTP ${response.status} ${response.statusText}`.trim();
+}
+export async function validateHubspotToken(token, fetchImpl = fetch) {
+    const response = await fetchImpl(`${HS_API_URL}/crm/v3/owners?limit=1`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (response.ok) {
+        return { ok: true, detail: "Token accepted by the HubSpot CRM API." };
+    }
+    const body = await response.text();
+    return { ok: false, detail: `HubSpot rejected the token (${response.status}): ${body}` };
+}
+async function tokenRequest(params, fetchImpl) {
+    const response = await fetchImpl(HS_TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams(params).toString(),
+    });
+    if (!response.ok) {
+        throw new Error(`HubSpot token request failed: ${await safeTokenError(response)}`);
+    }
+    const data = await response.json();
+    if (!data.access_token)
+        throw new Error("HubSpot token response had no access_token.");
+    return {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        expiresAt: Date.now() + (data.expires_in ?? 1800) * 1000,
+    };
+}
+export async function exchangeHubspotCode(options) {
+    return tokenRequest({
+        grant_type: "authorization_code",
+        client_id: options.clientId,
+        client_secret: options.clientSecret,
+        redirect_uri: options.redirectUri,
+        code: options.code,
+    }, options.fetchImpl ?? fetch);
+}
+export async function refreshHubspotToken(options) {
+    return tokenRequest({
+        grant_type: "refresh_token",
+        client_id: options.clientId,
+        client_secret: options.clientSecret,
+        refresh_token: options.refreshToken,
+    }, options.fetchImpl ?? fetch);
+}
+/**
+ * RFC 8252 loopback OAuth: serve one request on 127.0.0.1, send the user to
+ * the provider consent page, capture the code locally, exchange it directly.
+ */
+export async function runHubspotLoopbackLogin(options) {
+    const port = options.port ?? DEFAULT_LOOPBACK_PORT;
+    const scopes = options.scopes ?? DEFAULT_OAUTH_SCOPES;
+    const log = options.log ?? ((message) => console.error(message));
+    const redirectUri = `http://localhost:${port}/callback`;
+    const state = randomBytes(16).toString("hex");
+    const code = await new Promise((resolve, reject) => {
+        const server = createServer((request, response) => {
+            const url = new URL(request.url ?? "/", `http://localhost:${port}`);
+            if (url.pathname !== "/callback") {
+                response.writeHead(404).end();
+                return;
+            }
+            const receivedState = url.searchParams.get("state");
+            const receivedCode = url.searchParams.get("code");
+            const error = url.searchParams.get("error");
+            response.writeHead(200, { "Content-Type": "text/html" });
+            response.end("<html><body><p>FullStackGTM CLI login complete. You can close this tab.</p></body></html>");
+            server.close();
+            clearTimeout(timer);
+            if (error) {
+                reject(new Error(`HubSpot authorization failed: ${error}`));
+            }
+            else if (receivedState !== state) {
+                reject(new Error("OAuth state mismatch; aborting login."));
+            }
+            else if (!receivedCode) {
+                reject(new Error("HubSpot redirected without an authorization code."));
+            }
+            else {
+                resolve(receivedCode);
+            }
+        });
+        const timer = setTimeout(() => {
+            server.close();
+            reject(new Error("Timed out waiting for the OAuth redirect."));
+        }, options.timeoutMs ?? 5 * 60 * 1000);
+        server.on("error", (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        server.listen(port, "127.0.0.1", () => {
+            const authorizeUrl = `${HS_AUTH_URL}?` +
+                new URLSearchParams({
+                    response_type: "code",
+                    client_id: options.clientId,
+                    redirect_uri: redirectUri,
+                    scope: scopes.join(" "),
+                    state,
+                }).toString();
+            log(`Open this URL to authorize (waiting on ${redirectUri}):\n\n  ${authorizeUrl}\n`);
+            void (options.openUrl ?? openInBrowser)(authorizeUrl);
+        });
+    });
+    return exchangeHubspotCode({
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        redirectUri,
+        code,
+        fetchImpl: options.fetchImpl,
+    });
+}
+export async function openInBrowser(url) {
+    // The URL may come from an external source (e.g. a broker deployment's
+    // verification URL). Only ever hand a well-formed http(s) URL to the OS
+    // opener — this prevents a leading `-` from being read as a flag by
+    // xdg-open and refuses non-web schemes outright.
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        return;
+    const safeUrl = parsed.toString();
+    const { spawn } = await import("node:child_process");
+    try {
+        if (process.platform === "darwin") {
+            spawn("open", [safeUrl], { stdio: "ignore", detached: true }).on("error", () => { });
+        }
+        else if (process.platform === "win32") {
+            // `start` is a cmd builtin, not an executable; the empty "" is the
+            // window title so a URL with characters isn't mis-parsed as the title.
+            spawn("cmd", ["/c", "start", "", safeUrl], { stdio: "ignore", detached: true }).on("error", () => { });
+        }
+        else {
+            // `--` ends option parsing so the URL is never treated as a flag.
+            spawn("xdg-open", ["--", safeUrl], { stdio: "ignore", detached: true }).on("error", () => { });
+        }
+    }
+    catch {
+        // Printing the URL is the contract; opening a browser is best-effort.
+    }
+}

package/dist/connectors/salesforce.d.ts

@@ -0,0 +1,26 @@
+import { type FieldMappings } from "../mappings.ts";
+import type { GtmConnector } from "../types.ts";
+export type SalesforceConnection = {
+    accessToken: string;
+    /** e.g. https://yourorg.my.salesforce.com */
+    instanceUrl: string;
+};
+export type SalesforceConnectorOptions = {
+    /** Returns an access token plus the instance URL it belongs to. */
+    getConnection: () => SalesforceConnection | Promise<SalesforceConnection>;
+    /** Per-org canonical-to-provider field overrides. Defaults cover standard fields. */
+    fieldMappings?: FieldMappings;
+    apiVersion?: string;
+    /** Injectable fetch for testing. */
+    fetchImpl?: typeof fetch;
+};
+/**
+ * Reference connector for Salesforce.
+ *
+ * Reads run SOQL with cursor pagination; writes PATCH sobjects directly.
+ * Like the HubSpot connector, it never drops records it cannot fully resolve
+ * (ownerless or amountless opportunities are returned so audit rules can
+ * surface the gaps). Probabilities are normalized to 0..1 to match the
+ * canonical model.
+ */
+export declare function createSalesforceConnector(options: SalesforceConnectorOptions): Required<GtmConnector>;

package/dist/connectors/salesforce.js

@@ -0,0 +1,318 @@
+import { SALESFORCE_DEFAULT_FIELD_MAPPINGS, mappedField, mappedFields, readMappedValue, } from "../mappings.js";
+const DEFAULT_API_VERSION = "v59.0";
+const SOBJECT_TYPES = {
+    account: "Account",
+    contact: "Contact",
+    deal: "Opportunity",
+};
+const MAPPING_OBJECT_TYPES = {
+    account: "accounts",
+    contact: "contacts",
+    deal: "deals",
+};
+/**
+ * Reference connector for Salesforce.
+ *
+ * Reads run SOQL with cursor pagination; writes PATCH sobjects directly.
+ * Like the HubSpot connector, it never drops records it cannot fully resolve
+ * (ownerless or amountless opportunities are returned so audit rules can
+ * surface the gaps). Probabilities are normalized to 0..1 to match the
+ * canonical model.
+ */
+export function createSalesforceConnector(options) {
+    const apiVersion = options.apiVersion ?? DEFAULT_API_VERSION;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const mappings = options.fieldMappings;
+    async function request(path, init = {}) {
+        const connection = await options.getConnection();
+        const url = path.startsWith("http")
+            ? path
+            : `${connection.instanceUrl.replace(/\/$/, "")}${path}`;
+        const response = await fetchImpl(url, {
+            ...init,
+            headers: {
+                Authorization: `Bearer ${connection.accessToken}`,
+                "Content-Type": "application/json",
+                ...(init.headers ?? {}),
+            },
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`Salesforce API error ${response.status}: ${body}`);
+        }
+        // Salesforce PATCH returns 204 No Content on success.
+        const text = await response.text();
+        return text ? JSON.parse(text) : null;
+    }
+    async function query(soql) {
+        const records = [];
+        let next = `/services/data/${apiVersion}/query?q=${encodeURIComponent(soql)}`;
+        const seen = new Set();
+        while (next) {
+            // Defend against a repeated nextRecordsUrl (would loop forever).
+            if (seen.has(next))
+                break;
+            seen.add(next);
+            const data = await request(next);
+            records.push(...(data?.records ?? []));
+            next = data?.nextRecordsUrl ?? undefined;
+        }
+        return records;
+    }
+    function readMapped(source, objectType, targetField, fallbackField) {
+        return readMappedValue(source, mappings, objectType, targetField, fallbackField);
+    }
+    function selectFields(objectType) {
+        return mappedFields(mappings, objectType, SALESFORCE_DEFAULT_FIELD_MAPPINGS[objectType]).join(", ");
+    }
+    async function assembleSnapshot(whereClause) {
+        const sfUsers = await query(`SELECT ${selectFields("owners")} FROM User${whereClause}`);
+        const users = sfUsers.map((user) => {
+            const id = String(readMapped(user, "owners", "id", "Id"));
+            const email = stringOrUndefined(readMapped(user, "owners", "email", "Email"));
+            return {
+                id,
+                provider: "salesforce",
+                crmId: id,
+                identities: [{ provider: "salesforce", externalId: id }],
+                name: stringOrFallback(readMapped(user, "owners", "name", "Name"), email ?? `User ${id}`),
+                email,
+                title: stringOrUndefined(readMapped(user, "owners", "title", "Title")),
+                active: Boolean(readMapped(user, "owners", "isActive", "IsActive")),
+            };
+        });
+        const sfAccounts = await query(`SELECT ${selectFields("accounts")} FROM Account${whereClause}`);
+        const accounts = sfAccounts.map((account) => {
+            const id = String(readMapped(account, "accounts", "id", "Id"));
+            return {
+                id,
+                provider: "salesforce",
+                crmId: id,
+                identities: [{ provider: "salesforce", externalId: id }],
+                name: stringOrFallback(readMapped(account, "accounts", "name", "Name"), "Unknown Account"),
+                domain: stringOrUndefined(readMapped(account, "accounts", "domain", "Website")),
+                industry: stringOrUndefined(readMapped(account, "accounts", "industry", "Industry")),
+                employeeCount: numberOrUndefined(readMapped(account, "accounts", "employeeCount", "NumberOfEmployees")),
+                annualRevenue: numberOrUndefined(readMapped(account, "accounts", "annualRevenue", "AnnualRevenue")),
+                ownerId: stringOrUndefined(readMapped(account, "accounts", "ownerId", "OwnerId")),
+                raw: account,
+            };
+        });
+        const sfContacts = await query(`SELECT ${selectFields("contacts")} FROM Contact${whereClause}`);
+        const contacts = sfContacts.map((contact) => {
+            const id = String(readMapped(contact, "contacts", "id", "Id"));
+            return {
+                id,
+                provider: "salesforce",
+                crmId: id,
+                identities: [{ provider: "salesforce", externalId: id }],
+                accountId: stringOrUndefined(readMapped(contact, "contacts", "accountId", "AccountId")),
+                firstName: stringOrUndefined(readMapped(contact, "contacts", "firstName", "FirstName")),
+                lastName: stringOrUndefined(readMapped(contact, "contacts", "lastName", "LastName")),
+                email: stringOrUndefined(readMapped(contact, "contacts", "email", "Email")),
+                phone: stringOrUndefined(readMapped(contact, "contacts", "phone", "Phone")),
+                title: stringOrUndefined(readMapped(contact, "contacts", "title", "Title")),
+                ownerId: stringOrUndefined(readMapped(contact, "contacts", "ownerId", "OwnerId")),
+                raw: contact,
+            };
+        });
+        const sfOpportunities = await query(`SELECT ${selectFields("deals")} FROM Opportunity${whereClause}`);
+        const deals = sfOpportunities.map((opportunity) => {
+            const id = String(readMapped(opportunity, "deals", "id", "Id"));
+            const probability = numberOrUndefined(readMapped(opportunity, "deals", "probability", "Probability"));
+            const isClosed = Boolean(readMapped(opportunity, "deals", "isClosed", "IsClosed"));
+            const isWon = Boolean(readMapped(opportunity, "deals", "isWon", "IsWon"));
+            const forecastCategoryName = stringOrUndefined(readMapped(opportunity, "deals", "forecastCategoryName", "ForecastCategory"));
+            const forecastCategory = isWon
+                ? "closed_won"
+                : isClosed
+                    ? "closed_lost"
+                    : // Map Salesforce's native ForecastCategory (e.g. "BestCase",
+                        // "Commit", "Pipeline") to the canonical snake_case form, falling
+                        // back to "pipeline" when absent.
+                        (forecastCategoryName
+                            ? forecastCategoryName
+                                .replace(/([a-z])([A-Z])/g, "$1_$2")
+                                .toLowerCase()
+                            : "pipeline");
+            return {
+                id,
+                provider: "salesforce",
+                crmId: id,
+                identities: [{ provider: "salesforce", externalId: id }],
+                accountId: stringOrUndefined(readMapped(opportunity, "deals", "accountId", "AccountId")),
+                ownerId: stringOrUndefined(readMapped(opportunity, "deals", "ownerId", "OwnerId")),
+                name: stringOrFallback(readMapped(opportunity, "deals", "name", "Name"), "Untitled Opportunity"),
+                amount: numberOrUndefined(readMapped(opportunity, "deals", "amount", "Amount")),
+                stage: stringOrUndefined(readMapped(opportunity, "deals", "stage", "StageName")),
+                closeDate: stringOrUndefined(readMapped(opportunity, "deals", "closeDate", "CloseDate"))?.split("T")[0],
+                dealType: stringOrUndefined(readMapped(opportunity, "deals", "dealType", "Type")),
+                forecastCategory,
+                // Salesforce probabilities are 0..100; canonical is 0..1.
+                probability: probability === undefined ? undefined : probability / 100,
+                isClosed,
+                isWon,
+                lastActivityAt: stringOrUndefined(readMapped(opportunity, "deals", "lastActivityAt", "LastActivityDate")),
+                raw: opportunity,
+            };
+        });
+        return {
+            generatedAt: new Date().toISOString(),
+            provider: "salesforce",
+            users,
+            accounts,
+            contacts,
+            deals,
+            // Task/Event reads come with engagement support; staleness falls back
+            // to close dates until then.
+            activities: [],
+        };
+    }
+    async function fetchSnapshot() {
+        return assembleSnapshot("");
+    }
+    /** Records modified since `sinceIso`, filtered on `SystemModstamp`. */
+    async function fetchChanges(sinceIso) {
+        const sinceMs = Date.parse(sinceIso);
+        if (!Number.isFinite(sinceMs))
+            throw new Error(`Invalid since timestamp: ${sinceIso}`);
+        return assembleSnapshot(` WHERE SystemModstamp >= ${new Date(sinceMs).toISOString()}`);
+    }
+    function humanizeField(field) {
+        return field
+            .replace(/_task$/, "")
+            .replace(/[_-]+/g, " ")
+            .replace(/\b\w/g, (c) => c.toUpperCase())
+            .trim();
+    }
+    async function setField(operation) {
+        const sobjectType = SOBJECT_TYPES[operation.objectType];
+        const mappingType = MAPPING_OBJECT_TYPES[operation.objectType];
+        if (!sobjectType || !mappingType || !operation.field) {
+            return {
+                operationId: operation.id,
+                status: "skipped",
+                detail: "Field writes are only supported for accounts, contacts, and deals with an explicit field.",
+            };
+        }
+        const defaults = SALESFORCE_DEFAULT_FIELD_MAPPINGS[mappingType] ?? {};
+        const field = mappedField(mappings, mappingType, operation.field, defaults[operation.field] ?? operation.field);
+        const value = operation.operation === "clear_field" ? null : String(operation.afterValue ?? "");
+        await request(`/services/data/${apiVersion}/sobjects/${sobjectType}/${encodeURIComponent(operation.objectId)}`, { method: "PATCH", body: JSON.stringify({ [field]: value }) });
+        return {
+            operationId: operation.id,
+            status: "applied",
+            detail: `Set ${field} on ${sobjectType}/${operation.objectId}.`,
+            providerData: { sobjectType, field },
+        };
+    }
+    async function createTask(operation) {
+        // Salesforce activities relate via WhatId (account/opportunity) or WhoId
+        // (contact). Subject is required.
+        const reference = operation.objectType === "contact"
+            ? { WhoId: operation.objectId }
+            : operation.objectType === "account" || operation.objectType === "deal"
+                ? { WhatId: operation.objectId }
+                : null;
+        if (!reference) {
+            return {
+                operationId: operation.id,
+                status: "skipped",
+                detail: "Tasks can be attached to accounts, contacts, and deals.",
+            };
+        }
+        const response = await request(`/services/data/${apiVersion}/sobjects/Task`, {
+            method: "POST",
+            body: JSON.stringify({
+                Subject: operation.field ? humanizeField(operation.field) : "Follow up",
+                Description: String(operation.afterValue ?? operation.reason ?? ""),
+                Status: "Not Started",
+                Priority: "Normal",
+                ...reference,
+            }),
+        });
+        return {
+            operationId: operation.id,
+            status: "applied",
+            detail: `Created task on ${operation.objectType}/${operation.objectId}.`,
+            providerData: { id: response?.id },
+        };
+    }
+    async function archiveRecord(operation) {
+        const sobjectType = SOBJECT_TYPES[operation.objectType];
+        if (!sobjectType) {
+            return {
+                operationId: operation.id,
+                status: "skipped",
+                detail: "archive_record is supported for accounts, contacts, and deals.",
+            };
+        }
+        await request(`/services/data/${apiVersion}/sobjects/${sobjectType}/${encodeURIComponent(operation.objectId)}`, { method: "DELETE" });
+        return {
+            operationId: operation.id,
+            status: "applied",
+            detail: `Deleted ${sobjectType}/${operation.objectId}.`,
+        };
+    }
+    async function applyOperation(operation) {
+        try {
+            switch (operation.operation) {
+                case "set_field":
+                case "clear_field":
+                    // link_record on a deal is just setting AccountId in Salesforce.
+                    return await setField(operation);
+                case "link_record":
+                    return await setField({ ...operation, operation: "set_field" });
+                case "create_task":
+                    return await createTask(operation);
+                case "archive_record":
+                    return await archiveRecord(operation);
+                default:
+                    return {
+                        operationId: operation.id,
+                        status: "skipped",
+                        detail: `Unknown operation ${operation.operation}.`,
+                    };
+            }
+        }
+        catch (error) {
+            return {
+                operationId: operation.id,
+                status: "failed",
+                detail: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    async function readField(objectType, objectId, field) {
+        const sobjectType = SOBJECT_TYPES[objectType];
+        const mappingType = MAPPING_OBJECT_TYPES[objectType];
+        if (!sobjectType || !mappingType) {
+            throw new Error(`Field reads are only supported for accounts, contacts, and deals.`);
+        }
+        const defaults = SALESFORCE_DEFAULT_FIELD_MAPPINGS[mappingType] ?? {};
+        const sfField = mappedField(mappings, mappingType, field, defaults[field] ?? field);
+        const data = await request(`/services/data/${apiVersion}/sobjects/${sobjectType}/${encodeURIComponent(objectId)}?fields=${encodeURIComponent(sfField)}`);
+        return data?.[sfField] ?? null;
+    }
+    return {
+        provider: "salesforce",
+        fetchSnapshot,
+        fetchChanges,
+        applyOperation,
+        readField,
+    };
+}
+function stringOrUndefined(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    return String(value);
+}
+function stringOrFallback(value, fallback) {
+    return stringOrUndefined(value) ?? fallback;
+}
+function numberOrUndefined(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    const parsed = typeof value === "number" ? value : Number.parseFloat(String(value));
+    return Number.isFinite(parsed) ? parsed : undefined;
+}

package/dist/connectors/salesforceAuth.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Salesforce CLI authentication.
+ *
+ * Salesforce supports the device-authorization grant natively, which is the
+ * ideal CLI shape: no localhost server, no client secret — just a code the
+ * user confirms on any device. Requires a Connected App with device flow
+ * enabled; only its consumer key (client id) is needed.
+ */
+export type SalesforceTokenSet = {
+    accessToken: string;
+    refreshToken?: string;
+    instanceUrl: string;
+    /** Conservative local expiry; Salesforce session length is org-defined. */
+    expiresAt: number;
+};
+export type SalesforceDeviceAuthorization = {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    intervalSeconds: number;
+};
+export declare function startSalesforceDeviceLogin(options: {
+    clientId: string;
+    loginUrl?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<SalesforceDeviceAuthorization>;
+export declare function pollSalesforceDeviceLogin(options: {
+    clientId: string;
+    deviceCode: string;
+    intervalSeconds: number;
+    loginUrl?: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<SalesforceTokenSet>;
+export declare function refreshSalesforceToken(options: {
+    clientId: string;
+    refreshToken: string;
+    loginUrl?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<SalesforceTokenSet>;
+export declare function validateSalesforceToken(accessToken: string, instanceUrl: string, fetchImpl?: typeof fetch): Promise<{
+    ok: boolean;
+    detail: string;
+}>;