Hubspot Agency Multi Portal

// Shape of the credential store (stored in secret manager, NOT in git or env vars)
interface PortalCredentialStore {
  version: number; // increment on every write; used for drift detection
  portals: Record<string, PortalCredential>;
}

interface PortalCredential {
  token: string;            // HubSpot private-app token: pat-na1-...
  portalId: number;         // HubSpot portal ID — verified via account-info on onboard
  clientSlug: string;       // kebab-case client identifier: "acme-corp"
  addedAt: string;          // ISO 8601 — when this credential was seeded
  lastRotatedAt: string;    // ISO 8601 — updated on every token rotation
  datacenter: string;       // "na1" | "eu1" | "au1" — extracted from token prefix
}

// Load from secret manager at process startup — never re-read per-request
async function loadCredentialStore(): Promise<PortalCredentialStore> {
  const raw = await readSecret("hubspot/agency-portals");
  const store: PortalCredentialStore = JSON.parse(raw);
  if (!store.portals || typeof store.portals !== "object") {
    throw new Error("Credential store is malformed — missing portals map");
  }
  return store;
}

interface PortalDetails {
  portalId: number;
  timeZone: string;
  currency: string;
  portalType: string; // "STANDARD" | "DEVELOPER" | "SANDBOX" | "TRIAL"
}

async function verifyPortalIdentity(
  token: string,
  expectedPortalId?: number
): Promise<PortalDetails> {
  const res = await fetch("https://api.hubapi.com/account-info/v3/details", {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (res.status === 401) {
    throw new Error("Token rejected (401) — revoked, malformed, or wrong datacenter");
  }
  if (res.status === 403) {
    throw new Error("Token lacks account-info scope — re-create private app with account-info scope");
  }
  if (!res.ok) {
    throw new Error(`account-info returned ${res.status}: ${await res.text()}`);
  }

  const details: PortalDetails = await res.json();

  if (expectedPortalId !== undefined && details.portalId !== expectedPortalId) {
    throw new Error(
      `Portal ID mismatch — token belongs to portal ${details.portalId}, ` +
      `expected ${expectedPortalId}. Token is for the wrong client.`
    );
  }

  return details;
}

interface AuditRecord {
  ts: string;           // ISO 8601 timestamp
  portalId: number;
  clientSlug: string;
  method: string;       // GET | POST | PATCH | DELETE
  path: string;         // /crm/v3/objects/contacts
  statusCode: number;
  durationMs: number;
  objectType?: string;  // "contacts" | "deals" | "companies" — extracted from path
  objectId?: string;    // from path or response body
  actor: string;        // "hubspot-agency-router/2.0.0"
  rateLimitRemaining?: number; // from X-HubSpot-RateLimit-Daily-Remaining header
}

type AuditWriter = (record: AuditRecord) => void | Promise<void>;

function createPortalClient(
  credential: PortalCredential,
  auditWriter: AuditWriter
) {
  const baseUrl = "https://api.hubapi.com";

  return async function portalFetch(
    path: string,
    init: RequestInit = {}
  ): Promise<Response> {
    const start = Date.now();
    const method = (init.method ?? "GET").toUpperCase();

    const res = await fetch(`${baseUrl}${path}`, {
      ...init,
      headers: {
        Authorization: `Bearer ${credential.token}`,
        "Content-Type": "application/json",
        ...init.headers,
      },
    });

    const durationMs = Date.now() - start;
    const objectType = extractObjectType(path);
    const objectId = extractObjectId(path);

    const record: AuditRecord = {
      ts: new Date().toISOString(),
      portalId: credential.portalId,
      clientSlug: credential.clientSlug,
      method,
      path,
      statusCode: res.status,
      durationMs,
      objectType,
      objectId,
      actor: "hubspot-agency-router/2.0.0",
      rateLimitRemaining: parseInt(
        res.headers.get("X-HubSpot-RateLimit-Daily-Remaining") ?? "0",
        10
      ),
    };

    // Fire-and-forget — do not block the response on audit write
    Promise.resolve(auditWriter(record)).catch((err) => {
      console.error("Audit write failed — call was NOT prevented:", err);
    });

    return res;
  };
}

function extractObjectType(path: string): string | undefined {
  const match = path.match(/\/crm\/v\d+\/objects\/([^/?]+)/);
  return match?.[1];
}

function extractObjectId(path: string): string | undefined {
  const match = path.match(/\/crm\/v\d+\/objects\/[^/?]+\/(\d+)/);
  return match?.[1];
}

class HubSpotAgencyRouter {
  private store: PortalCredentialStore;
  private clientCache = new Map<string, ReturnType<typeof createPortalClient>>();
  private auditWriter: AuditWriter;

  constructor(store: PortalCredentialStore, auditWriter: AuditWriter) {
    this.store = store;
    this.auditWriter = auditWriter;
  }

  getClient(clientSlug: string): ReturnType<typeof createPortalClient> {
    if (!this.store.portals[clientSlug]) {
      throw new Error(
        `No credential found for client slug "${clientSlug}". ` +
        `Available slugs: ${Object.keys(this.store.portals).join(", ")}`
      );
    }
    if (!this.clientCache.has(clientSlug)) {
      this.clientCache.set(
        clientSlug,
        createPortalClient(this.store.portals[clientSlug], this.auditWriter)
      );
    }
    return this.clientCache.get(clientSlug)!;
  }

  listClients(): string[] {
    return Object.keys(this.store.portals).sort();
  }

  getPortalId(clientSlug: string): number {
    const cred = this.store.portals[clientSlug];
    if (!cred) throw new Error(`Unknown client slug: ${clientSlug}`);
    return cred.portalId;
  }
}

// Startup
const store = await loadCredentialStore();
const router = new HubSpotAgencyRouter(store, (record) => {
  process.stdout.write(JSON.stringify(record) + "\n");
});

// Usage — every call is slug-scoped; no ambient credential
const client = router.getClient("acme-corp");
const contacts = await client("/crm/v3/objects/contacts?limit=10");

const RATE_LIMIT_WARN_THRESHOLD = 50_000; // warn at 50K remaining of 500K daily

// Inside the audit writer
function checkRateLimit(record: AuditRecord): void {
  if (
    record.rateLimitRemaining !== undefined &&
    record.rateLimitRemaining < RATE_LIMIT_WARN_THRESHOLD
  ) {
    console.warn(JSON.stringify({
      event: "rate_limit_warning",
      clientSlug: record.clientSlug,
      portalId: record.portalId,
      dailyRemaining: record.rateLimitRemaining,
      threshold: RATE_LIMIT_WARN_THRESHOLD,
    }));
  }
}