fullstackgtm 0.10.0

package/src/connectors/salesforceAuth.ts

@@ -0,0 +1,167 @@
+/**
+ * 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.
+ */
+
+const DEFAULT_LOGIN_URL = "https://login.salesforce.com";
+
+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;
+};
+
+const SESSION_TTL_MS = 2 * 60 * 60 * 1000;
+
+function tokenUrl(loginUrl: string) {
+  return `${loginUrl.replace(/\/$/, "")}/services/oauth2/token`;
+}
+
+/**
+ * OAuth error responses can echo request parameters. Surface only the
+ * standard `error`/`error_description` fields, never the raw body.
+ */
+async function safeTokenError(response: Response): Promise<string> {
+  let description: string | undefined;
+  try {
+    const data = await response.json();
+    description = data?.error_description ?? data?.error;
+  } 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 startSalesforceDeviceLogin(options: {
+  clientId: string;
+  loginUrl?: string;
+  fetchImpl?: typeof fetch;
+}): Promise<SalesforceDeviceAuthorization> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const response = await fetchImpl(tokenUrl(options.loginUrl ?? DEFAULT_LOGIN_URL), {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      response_type: "device_code",
+      client_id: options.clientId,
+      scope: "api refresh_token",
+    }).toString(),
+  });
+  if (!response.ok) {
+    throw new Error(`Salesforce device authorization failed: ${await safeTokenError(response)}`);
+  }
+  const data = await response.json();
+  return {
+    deviceCode: data.device_code,
+    userCode: data.user_code,
+    verificationUri: data.verification_uri,
+    intervalSeconds: Number(data.interval ?? 5),
+  };
+}
+
+export async function pollSalesforceDeviceLogin(options: {
+  clientId: string;
+  deviceCode: string;
+  intervalSeconds: number;
+  loginUrl?: string;
+  timeoutMs?: number;
+  fetchImpl?: typeof fetch;
+}): Promise<SalesforceTokenSet> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const url = tokenUrl(options.loginUrl ?? DEFAULT_LOGIN_URL);
+  const deadline = Date.now() + (options.timeoutMs ?? 10 * 60 * 1000);
+  let intervalMs = Math.max(1, options.intervalSeconds) * 1000;
+
+  while (Date.now() < deadline) {
+    await new Promise((resolveSleep) => setTimeout(resolveSleep, intervalMs));
+    const response = await fetchImpl(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "device",
+        client_id: options.clientId,
+        code: options.deviceCode,
+      }).toString(),
+    });
+    const data = await response.json().catch(() => ({}));
+    if (response.ok && data.access_token && data.instance_url) {
+      return {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        instanceUrl: data.instance_url,
+        expiresAt: Date.now() + SESSION_TTL_MS,
+      };
+    }
+    if (data.error === "authorization_pending") continue;
+    if (data.error === "slow_down") {
+      intervalMs += 5000;
+      continue;
+    }
+    throw new Error(
+      `Salesforce device login failed: ${data.error_description ?? data.error ?? response.status}`,
+    );
+  }
+  throw new Error("Timed out waiting for Salesforce device authorization.");
+}
+
+export async function refreshSalesforceToken(options: {
+  clientId: string;
+  refreshToken: string;
+  loginUrl?: string;
+  fetchImpl?: typeof fetch;
+}): Promise<SalesforceTokenSet> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const response = await fetchImpl(tokenUrl(options.loginUrl ?? DEFAULT_LOGIN_URL), {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      client_id: options.clientId,
+      refresh_token: options.refreshToken,
+    }).toString(),
+  });
+  if (!response.ok) {
+    throw new Error(`Salesforce token refresh failed: ${await safeTokenError(response)}`);
+  }
+  const data = await response.json();
+  if (!data.access_token || !data.instance_url) {
+    throw new Error("Salesforce refresh response had no access_token/instance_url.");
+  }
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token ?? options.refreshToken,
+    instanceUrl: data.instance_url,
+    expiresAt: Date.now() + SESSION_TTL_MS,
+  };
+}
+
+export async function validateSalesforceToken(
+  accessToken: string,
+  instanceUrl: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ ok: boolean; detail: string }> {
+  const response = await fetchImpl(
+    `${instanceUrl.replace(/\/$/, "")}/services/oauth2/userinfo`,
+    { headers: { Authorization: `Bearer ${accessToken}` } },
+  );
+  if (response.ok) {
+    return { ok: true, detail: "Token accepted by the Salesforce API." };
+  }
+  const body = await response.text();
+  return { ok: false, detail: `Salesforce rejected the token (${response.status}): ${body}` };
+}

package/src/connectors/stripe.ts

@@ -0,0 +1,215 @@
+import type {
+  CanonicalAccount,
+  CanonicalContact,
+  CanonicalDeal,
+  CanonicalGtmSnapshot,
+  GtmConnector,
+  PatchOperation,
+  PatchOperationResult,
+} from "../types.ts";
+
+const DEFAULT_API_BASE_URL = "https://api.stripe.com";
+
+export type StripeConnectorOptions = {
+  /** Stripe secret key (sk_...) or restricted key. */
+  getApiKey: () => string | Promise<string>;
+  apiBaseUrl?: string;
+  /** Injectable fetch for testing. */
+  fetchImpl?: typeof fetch;
+};
+
+/**
+ * Read-only billing connector for Stripe — the first non-CRM connector,
+ * proving the GtmConnector contract generalizes to billing systems.
+ *
+ * Semantics:
+ * - READ-ONLY: `applyOperation` always returns a `skipped` result and never
+ *   writes to Stripe; `readField` is intentionally not implemented, so apply
+ *   orchestration treats every field as unreadable rather than guessing.
+ * - Customers map to canonical accounts, plus a canonical contact when the
+ *   customer has an email address.
+ * - Subscriptions map to canonical deals: active/trialing subscriptions are
+ *   closed-won, canceled/incomplete_expired/unpaid are closed-lost, and
+ *   anything else (e.g. past_due, incomplete) is still open.
+ * - Stripe amounts are minor units (cents); the canonical model uses major
+ *   units, so amounts are divided by 100 at this boundary.
+ * - Billing systems have no sales users and no activities, so both
+ *   collections are always empty.
+ */
+export function createStripeConnector(options: StripeConnectorOptions): GtmConnector {
+  const baseUrl = (options.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
+  const fetchImpl = options.fetchImpl ?? fetch;
+
+  async function request(path: string): Promise<any> {
+    const apiKey = await options.getApiKey();
+    const response = await fetchImpl(`${baseUrl}${path}`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`Stripe API error ${response.status}: ${body}`);
+    }
+    return response.json();
+  }
+
+  /** Stripe list pagination: follow `has_more` with `starting_after=<last id>`. */
+  async function list(path: string): Promise<any[]> {
+    const results: any[] = [];
+    let startingAfter: string | undefined;
+    do {
+      const separator = path.includes("?") ? "&" : "?";
+      const data = await request(
+        `${path}${startingAfter ? `${separator}starting_after=${encodeURIComponent(startingAfter)}` : ""}`,
+      );
+      const page: any[] = data.data ?? [];
+      results.push(...page);
+      startingAfter =
+        data.has_more === true && page.length > 0 ? String(page.at(-1).id) : undefined;
+    } while (startingAfter);
+    return results;
+  }
+
+  async function assembleSnapshot(createdGte?: number): Promise<CanonicalGtmSnapshot> {
+    // Stripe filters list endpoints on the integer `created` field via
+    // created[gte]=<unix seconds>; omitted on a full snapshot.
+    const createdFilter =
+      createdGte === undefined ? "" : `&created[gte]=${createdGte}`;
+    const customers = await list(`/v1/customers?limit=100${createdFilter}`);
+    const accounts: CanonicalAccount[] = [];
+    const contacts: CanonicalContact[] = [];
+    for (const customer of customers) {
+      if (!customer.id) continue;
+      const id = String(customer.id);
+      const email = stringOrUndefined(customer.email);
+      // The email domain is the cross-system match key: mergeSnapshots
+      // collapses this billing account onto the same company's CRM account
+      // by domain, so revenue data lands on the right merged record.
+      const domain = email?.includes("@") ? email.split("@").at(-1)!.toLowerCase() : undefined;
+      accounts.push({
+        id,
+        provider: "stripe",
+        crmId: id,
+        identities: [{ provider: "stripe", externalId: id }],
+        name: stringOrUndefined(customer.name) ?? email ?? `Customer ${id}`,
+        domain,
+        raw: customer,
+      });
+      if (email) {
+        // Stripe customers carry a single billing email, not split names;
+        // name parts stay undefined so merge-by-email can fill them in.
+        contacts.push({
+          id: `${id}_contact`,
+          provider: "stripe",
+          crmId: id,
+          identities: [{ provider: "stripe", externalId: id }],
+          accountId: id,
+          email,
+          raw: customer,
+        });
+      }
+    }
+
+    const subscriptions = await list(
+      `/v1/subscriptions?status=all&limit=100${createdFilter}`,
+    );
+    const deals: CanonicalDeal[] = subscriptions
+      .filter((subscription) => subscription.id)
+      .map((subscription) => {
+        const id = String(subscription.id);
+        const items: any[] = subscription.items?.data ?? [];
+        const firstPrice = items[0]?.price;
+        const status = stringOrUndefined(subscription.status);
+        const isWon = status === "active" || status === "trialing";
+        const isLost =
+          status === "canceled" || status === "incomplete_expired" || status === "unpaid";
+        // Stripe prices are minor units (cents); canonical amounts are major
+        // units. Metered/tiered prices have a null unit_amount — their value
+        // isn't knowable from the subscription alone, so leave the amount
+        // undefined rather than understating it as 0 (an amountless deal the
+        // audit can flag, instead of a silently wrong number).
+        const hasUnpricedItem = items.some(
+          (item) => numberOrUndefined(item.price?.unit_amount) === undefined,
+        );
+        const amountCents = hasUnpricedItem
+          ? undefined
+          : items.reduce(
+              (sum, item) =>
+                sum +
+                (numberOrUndefined(item.price?.unit_amount) ?? 0) *
+                  (numberOrUndefined(item.quantity) ?? 1),
+              0,
+            );
+        return {
+          id,
+          provider: "stripe",
+          crmId: id,
+          identities: [{ provider: "stripe", externalId: id }],
+          accountId: stringOrUndefined(subscription.customer),
+          name: `Subscription ${firstPrice?.nickname ?? firstPrice?.id ?? id}`,
+          amount: amountCents === undefined ? undefined : amountCents / 100,
+          currency: stringOrUndefined(firstPrice?.currency)?.toUpperCase(),
+          stage: status,
+          isClosed: isWon || isLost,
+          isWon,
+          closeDate:
+            typeof subscription.start_date === "number"
+              ? new Date(subscription.start_date * 1000).toISOString().split("T")[0]
+              : undefined,
+          raw: subscription,
+        };
+      });
+
+    return {
+      generatedAt: new Date().toISOString(),
+      provider: "stripe",
+      // Billing systems have neither sales users nor activities.
+      users: [],
+      accounts,
+      contacts,
+      deals,
+      activities: [],
+    };
+  }
+
+  async function fetchSnapshot(): Promise<CanonicalGtmSnapshot> {
+    return assembleSnapshot();
+  }
+
+  /**
+   * Customers and subscriptions created since `sinceIso`. Stripe filters on the
+   * integer `created` field (unix seconds), so the ISO timestamp is converted
+   * to unix seconds for the `created[gte]` query param. Note this catches
+   * newly-created records only, not status changes on existing ones.
+   */
+  async function fetchChanges(sinceIso: string): Promise<CanonicalGtmSnapshot> {
+    const sinceMs = Date.parse(sinceIso);
+    if (!Number.isFinite(sinceMs)) throw new Error(`Invalid since timestamp: ${sinceIso}`);
+    return assembleSnapshot(Math.floor(sinceMs / 1000));
+  }
+
+  async function applyOperation(operation: PatchOperation): Promise<PatchOperationResult> {
+    return {
+      operationId: operation.id,
+      status: "skipped",
+      detail: "The stripe connector is read-only.",
+    };
+  }
+
+  return {
+    provider: "stripe",
+    fetchSnapshot,
+    fetchChanges,
+    applyOperation,
+  };
+}
+
+function stringOrUndefined(value: unknown): string | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  return String(value);
+}
+
+function numberOrUndefined(value: unknown): number | undefined {
+  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/src/credentials.ts

@@ -0,0 +1,282 @@
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { refreshHubspotToken } from "./connectors/hubspotAuth.ts";
+import { refreshSalesforceToken } from "./connectors/salesforceAuth.ts";
+
+/**
+ * Local CLI credential store: ~/.fullstackgtm/credentials.json (0600), or
+ * $FSGTM_HOME/credentials.json when set. Environment tokens always win over
+ * stored credentials so CI and agent sandboxes never touch the filesystem.
+ */
+
+export type StoredCredential = {
+  kind: "private_app" | "oauth" | "broker";
+  accessToken: string;
+  refreshToken?: string;
+  /** Epoch ms when the access token expires (oauth only). */
+  expiresAt?: number;
+  /** Client credentials kept for refresh when the user brings their own app. */
+  clientId?: string;
+  clientSecret?: string;
+  scopes?: string[];
+  /** Hosted FullStackGTM deployment the broker token belongs to. */
+  baseUrl?: string;
+  /** Salesforce instance URL the access token belongs to. */
+  instanceUrl?: string;
+  /** Salesforce login host used for device flow refresh. */
+  loginUrl?: string;
+  createdAt: string;
+  updatedAt: string;
+};
+
+type CredentialsFile = {
+  version: 1;
+  providers: Record<string, StoredCredential>;
+};
+
+export function credentialsDir(): string {
+  return process.env.FSGTM_HOME ?? join(homedir(), ".fullstackgtm");
+}
+
+export function credentialsPath(): string {
+  return join(credentialsDir(), "credentials.json");
+}
+
+/**
+ * Create the fullstackgtm home directory and force it to 0700 even if it
+ * already existed at looser permissions (mkdirSync's `mode` is ignored for
+ * existing directories, and is subject to umask for new ones). All writers of
+ * sensitive data under the home — credentials and plan files — go through
+ * this so directory permissions are actually enforced, not merely requested.
+ */
+export function ensureSecureHomeDir(): string {
+  const dir = credentialsDir();
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try {
+    chmodSync(dir, 0o700);
+  } catch {
+    // Non-POSIX filesystems (e.g. Windows) ignore chmod; nothing to enforce.
+  }
+  return dir;
+}
+
+/** Write a 0600 file under the home, enforcing the mode even on rewrite. */
+export function writeSecureFile(path: string, contents: string) {
+  writeFileSync(path, contents, { mode: 0o600 });
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    // Non-POSIX filesystems ignore chmod.
+  }
+}
+
+function readFile(): CredentialsFile {
+  try {
+    const parsed = JSON.parse(readFileSync(credentialsPath(), "utf8"));
+    if (parsed && typeof parsed === "object" && parsed.version === 1 && parsed.providers) {
+      return parsed as CredentialsFile;
+    }
+  } catch {
+    // Missing or unreadable file falls through to an empty store.
+  }
+  return { version: 1, providers: {} };
+}
+
+export function getCredential(provider: string): StoredCredential | null {
+  return readFile().providers[provider] ?? null;
+}
+
+export function storeCredential(provider: string, credential: StoredCredential) {
+  const file = readFile();
+  file.providers[provider] = credential;
+  ensureSecureHomeDir();
+  writeSecureFile(credentialsPath(), `${JSON.stringify(file, null, 2)}\n`);
+}
+
+export function deleteCredential(provider: string): boolean {
+  const file = readFile();
+  if (!file.providers[provider]) return false;
+  delete file.providers[provider];
+  if (Object.keys(file.providers).length === 0 && existsSync(credentialsPath())) {
+    unlinkSync(credentialsPath());
+    return true;
+  }
+  writeSecureFile(credentialsPath(), `${JSON.stringify(file, null, 2)}\n`);
+  return true;
+}
+
+const REFRESH_SKEW_MS = 2 * 60 * 1000;
+
+export type HubspotConnection = {
+  accessToken: string;
+  /** Org-level field mapping overrides, supplied by broker deployments. */
+  fieldMappings?: unknown;
+};
+
+/**
+ * Resolve HubSpot access from stored credentials. Direct logins win over the
+ * broker so an operator can always override the team default:
+ * 1. stored hubspot login (private app token, or OAuth with silent refresh)
+ * 2. stored broker pairing — exchanges the CLI token for a short-lived
+ *    provider token minted by the hosted deployment from the org's stored
+ *    sync credentials (and inherits the org's field mappings)
+ */
+export async function resolveHubspotConnection(
+  options: { fetchImpl?: typeof fetch } = {},
+): Promise<HubspotConnection | null> {
+  const credential = getCredential("hubspot");
+  if (credential) {
+    return { accessToken: await directHubspotToken(credential, options) };
+  }
+
+  const minted = await brokerMint("hubspot", options);
+  if (!minted) return null;
+  return { accessToken: minted.accessToken, fieldMappings: minted.fieldMappings };
+}
+
+export type SalesforceStoredConnection = {
+  accessToken: string;
+  instanceUrl: string;
+  /** Org-level field mapping overrides, supplied by broker deployments. */
+  fieldMappings?: unknown;
+};
+
+/**
+ * Resolve Salesforce access from stored credentials, same ladder shape as
+ * HubSpot: direct login (with silent device-flow refresh) wins over broker.
+ */
+export async function resolveSalesforceConnection(
+  options: { fetchImpl?: typeof fetch } = {},
+): Promise<SalesforceStoredConnection | null> {
+  const credential = getCredential("salesforce");
+  if (credential) {
+    if (!credential.instanceUrl) {
+      throw new Error(
+        "Stored Salesforce credential has no instance URL. Run `fullstackgtm login salesforce` again.",
+      );
+    }
+    const needsRefresh =
+      credential.kind === "oauth" &&
+      credential.expiresAt !== undefined &&
+      Date.now() > credential.expiresAt - REFRESH_SKEW_MS;
+    if (!needsRefresh) {
+      return { accessToken: credential.accessToken, instanceUrl: credential.instanceUrl };
+    }
+    if (!credential.refreshToken || !credential.clientId) {
+      throw new Error(
+        "Stored Salesforce token is expired and cannot be refreshed. Run `fullstackgtm login salesforce` again.",
+      );
+    }
+    const refreshed = await refreshSalesforceToken({
+      clientId: credential.clientId,
+      refreshToken: credential.refreshToken,
+      loginUrl: credential.loginUrl,
+      fetchImpl: options.fetchImpl,
+    });
+    storeCredential("salesforce", {
+      ...credential,
+      accessToken: refreshed.accessToken,
+      refreshToken: refreshed.refreshToken ?? credential.refreshToken,
+      instanceUrl: refreshed.instanceUrl,
+      expiresAt: refreshed.expiresAt,
+      updatedAt: new Date().toISOString(),
+    });
+    return { accessToken: refreshed.accessToken, instanceUrl: refreshed.instanceUrl };
+  }
+
+  const minted = await brokerMint("salesforce", options);
+  if (!minted) return null;
+  if (!minted.instanceUrl) {
+    throw new Error("The hosted deployment returned no Salesforce instance URL.");
+  }
+  return {
+    accessToken: minted.accessToken,
+    instanceUrl: minted.instanceUrl,
+    fieldMappings: minted.fieldMappings,
+  };
+}
+
+async function brokerMint(
+  provider: "hubspot" | "salesforce",
+  options: { fetchImpl?: typeof fetch },
+): Promise<{ accessToken: string; instanceUrl?: string; fieldMappings?: unknown } | null> {
+  const broker = getCredential("broker");
+  if (!broker?.baseUrl) return null;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const response = await fetchImpl(`${broker.baseUrl.replace(/\/$/, "")}/api/cli/token`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${broker.accessToken}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ provider }),
+  });
+  if (response.status === 401) {
+    throw new Error(
+      `The hosted deployment rejected this CLI's broker token. Run \`fullstackgtm login --via ${broker.baseUrl}\` again.`,
+    );
+  }
+  if (!response.ok) {
+    // Withhold the deployment's raw response body from the error.
+    throw new Error(
+      `Broker token exchange failed: HTTP ${response.status} ${response.statusText}`.trim(),
+    );
+  }
+  const connection = await response.json();
+  return {
+    accessToken: String(connection.accessToken),
+    instanceUrl: connection.instanceUrl ? String(connection.instanceUrl) : undefined,
+    fieldMappings: connection.fieldMappings ?? undefined,
+  };
+}
+
+/**
+ * Resolve a usable HubSpot access token (direct login or broker). Returns
+ * null when nothing is stored (callers fall back to instructions).
+ */
+export async function resolveHubspotAccessToken(
+  options: { fetchImpl?: typeof fetch } = {},
+): Promise<string | null> {
+  const connection = await resolveHubspotConnection(options);
+  return connection?.accessToken ?? null;
+}
+
+async function directHubspotToken(
+  credential: StoredCredential,
+  options: { fetchImpl?: typeof fetch },
+): Promise<string> {
+  const needsRefresh =
+    credential.kind === "oauth" &&
+    credential.expiresAt !== undefined &&
+    Date.now() > credential.expiresAt - REFRESH_SKEW_MS;
+
+  if (!needsRefresh) return credential.accessToken;
+  if (!credential.refreshToken || !credential.clientId || !credential.clientSecret) {
+    throw new Error(
+      "Stored HubSpot OAuth token is expired and cannot be refreshed. Run `fullstackgtm login hubspot` again.",
+    );
+  }
+
+  const refreshed = await refreshHubspotToken({
+    clientId: credential.clientId,
+    clientSecret: credential.clientSecret,
+    refreshToken: credential.refreshToken,
+    fetchImpl: options.fetchImpl,
+  });
+  storeCredential("hubspot", {
+    ...credential,
+    accessToken: refreshed.accessToken,
+    refreshToken: refreshed.refreshToken ?? credential.refreshToken,
+    expiresAt: refreshed.expiresAt,
+    updatedAt: new Date().toISOString(),
+  });
+  return refreshed.accessToken;
+}