@revfleet/hscli 0.8.12 → 0.9.0

package/dist/commands/workflows/preflight.js

@@ -0,0 +1,295 @@
+import { findPipelineStageTarget, isStandardObjectTypeId, loadMigrationIdMaps, stringifyId, } from "../../core/id-maps.js";
+import { CliError, printResult } from "../../core/output.js";
+import { parseJsonPayload } from "../crm/shared.js";
+const EMPTY_MAPS = {
+    subscriptionTypes: {},
+    businessUnits: {},
+    emails: {},
+    lists: {},
+    campaigns: {},
+    workflows: {},
+    users: {},
+    owners: {},
+    sequences: {},
+    customObjects: {},
+    associations: {},
+    pipelines: {},
+};
+const UNKNOWN_ID_KEY = /(?:^|[_-])(?:id|ids)$|(?:Id|Ids)$/;
+const SAFE_ID_KEYS = new Set([
+    "id",
+    "guid",
+    "actionId",
+    "actionTypeId",
+    "portalId",
+    "revisionId",
+    "createdAt",
+    "updatedAt",
+]);
+export function registerWorkflowPreflight(workflows, getCtx) {
+    workflows
+        .command("preflight")
+        .description("Check a workflow export for source-portal IDs before replay")
+        .requiredOption("--data <payload>", "Workflow JSON payload, array, or { results|workflows }")
+        .option("--id-map-dir <dir>", "Directory containing migration id-map JSON files")
+        .option("--strict", "Exit non-zero when broken references are found")
+        .action(async (opts) => {
+        const ctx = getCtx();
+        const result = preflightWorkflowsPayload(parseJsonPayload(opts.data), opts.idMapDir);
+        if (opts.strict && !result.ok) {
+            throw new CliError("WORKFLOW_PREFLIGHT_BROKEN_REFS", `Workflow preflight found ${result.brokenRefCount} unresolved source references`, undefined, result);
+        }
+        printResult(ctx, result);
+    });
+}
+export function preflightWorkflowsPayload(input, idMapDir) {
+    const maps = idMapDir ? loadMigrationIdMaps(idMapDir) : EMPTY_MAPS;
+    const workflows = normalizeWorkflows(input);
+    const checked = workflows.map((workflow, index) => inspectWorkflow(workflow, maps, index));
+    const brokenRefCount = checked.reduce((sum, workflow) => sum + workflow.brokenRefs.length, 0);
+    const warningCount = checked.reduce((sum, workflow) => sum + workflow.warnings.length, 0);
+    return {
+        ok: brokenRefCount === 0,
+        total: checked.length,
+        brokenRefCount,
+        warningCount,
+        workflows: checked,
+    };
+}
+function inspectWorkflow(workflow, maps, index) {
+    const brokenRefs = [];
+    const warnings = [];
+    const seenPaths = new Set();
+    const actions = records(workflow.actions);
+    actions.forEach((action, actionIndex) => {
+        const basePath = `workflows[${index}].actions[${actionIndex}]`;
+        inspectKnownRefs(action, basePath, maps, brokenRefs, seenPaths);
+        inspectPropertyValueRefs(action, basePath, maps, brokenRefs, seenPaths);
+        inspectUnknownIdFields(action, basePath, brokenRefs, seenPaths);
+    });
+    const enrollmentCriteria = record(workflow.enrollmentCriteria);
+    if (enrollmentCriteria) {
+        inspectKnownRefs(enrollmentCriteria, `workflows[${index}].enrollmentCriteria`, maps, brokenRefs, seenPaths);
+        inspectPropertyValueRefs(enrollmentCriteria, `workflows[${index}].enrollmentCriteria`, maps, brokenRefs, seenPaths);
+    }
+    const suppressionListIds = Array.isArray(workflow.suppressionListIds) ? workflow.suppressionListIds : [];
+    suppressionListIds.forEach((source, listIndex) => {
+        checkMapped(maps.lists, source, "suppressionList", `workflows[${index}].suppressionListIds[${listIndex}]`, brokenRefs, seenPaths);
+    });
+    return {
+        id: stringifyId(workflow.id),
+        name: typeof workflow.name === "string" ? workflow.name : undefined,
+        brokenRefs,
+        warnings,
+    };
+}
+function inspectKnownRefs(value, path, maps, brokenRefs, seenPaths) {
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => inspectKnownRefs(item, `${path}[${index}]`, maps, brokenRefs, seenPaths));
+        return;
+    }
+    const node = record(value);
+    if (!node)
+        return;
+    for (const [key, raw] of Object.entries(node)) {
+        const keyPath = `${path}.${key}`;
+        if (raw === undefined || raw === null)
+            continue;
+        if (["content_id", "email_content_id", "emailContentId", "emailId"].includes(key)) {
+            checkMapped(maps.emails, raw, "marketingEmail", keyPath, brokenRefs, seenPaths);
+        }
+        else if (["subscriptionId", "subscriptionTypeId", "subscription_type_id"].includes(key)) {
+            checkMapped(maps.subscriptionTypes, raw, "subscriptionType", keyPath, brokenRefs, seenPaths);
+        }
+        else if (["listId", "list_id", "staticListId"].includes(key)) {
+            checkMapped(maps.lists, raw, "list", keyPath, brokenRefs, seenPaths);
+        }
+        else if (["campaignId", "campaign_id"].includes(key)) {
+            checkMapped(maps.campaigns, raw, "campaign", keyPath, brokenRefs, seenPaths);
+        }
+        else if (["flow_id", "workflowId", "workflow_id"].includes(key)) {
+            checkMapped(maps.workflows, raw, "workflow", keyPath, brokenRefs, seenPaths);
+        }
+        else if (["userId", "user_id"].includes(key)) {
+            checkAnyMapped([maps.users, maps.owners], raw, "user", keyPath, brokenRefs, seenPaths);
+        }
+        else if (["sequenceId", "sequence_id"].includes(key)) {
+            checkMapped(maps.sequences, raw, "sequence", keyPath, brokenRefs, seenPaths);
+        }
+        else if (["object_type_id", "objectTypeId", "fromObjectType", "toObjectType"].includes(key)) {
+            checkCustomObjectMapped(maps.customObjects, raw, keyPath, brokenRefs, seenPaths);
+        }
+        else if (["labelToApply", "associationTypeId", "association_label_id"].includes(key)) {
+            checkMapped(maps.associations, raw, "associationLabel", keyPath, brokenRefs, seenPaths);
+        }
+        else if (["pipelineId", "pipeline_id"].includes(key)) {
+            checkPipelineMapped(maps, raw, keyPath, brokenRefs, seenPaths);
+        }
+        else if (["stageId", "stage_id"].includes(key)) {
+            checkStageMapped(maps, raw, keyPath, brokenRefs, seenPaths);
+        }
+        inspectKnownRefs(raw, keyPath, maps, brokenRefs, seenPaths);
+    }
+}
+function inspectPropertyValueRefs(value, path, maps, brokenRefs, seenPaths) {
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => inspectPropertyValueRefs(item, `${path}[${index}]`, maps, brokenRefs, seenPaths));
+        return;
+    }
+    const node = record(value);
+    if (!node)
+        return;
+    const propertyName = stringField(node, "propertyName")
+        ?? stringField(node, "targetProperty")
+        ?? stringField(node, "property")
+        ?? stringField(node, "name");
+    const rawValue = node.staticValue ?? node.value ?? node.values;
+    if (propertyName && rawValue !== undefined) {
+        const normalized = propertyName.toLowerCase();
+        if (normalized === "pipeline" || normalized === "hs_pipeline") {
+            checkPipelineMapped(maps, rawValue, `${path}.value`, brokenRefs, seenPaths);
+        }
+        if (normalized === "dealstage" || normalized === "hs_pipeline_stage" || normalized === "ticketstage") {
+            checkStageMapped(maps, rawValue, `${path}.value`, brokenRefs, seenPaths);
+        }
+    }
+    for (const [key, raw] of Object.entries(node)) {
+        inspectPropertyValueRefs(raw, `${path}.${key}`, maps, brokenRefs, seenPaths);
+    }
+}
+function inspectUnknownIdFields(value, path, brokenRefs, seenPaths) {
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => inspectUnknownIdFields(item, `${path}[${index}]`, brokenRefs, seenPaths));
+        return;
+    }
+    const node = record(value);
+    if (!node)
+        return;
+    for (const [key, raw] of Object.entries(node)) {
+        const keyPath = `${path}.${key}`;
+        if (!seenPaths.has(keyPath) && UNKNOWN_ID_KEY.test(key) && !SAFE_ID_KEYS.has(key) && hasIdLikeValue(raw)) {
+            seenPaths.add(keyPath);
+            brokenRefs.push({
+                path: keyPath,
+                kind: "unknown-id-field",
+                source: raw,
+                message: `Potential source ID field '${key}' has no explicit workflow remapper`,
+            });
+        }
+        inspectUnknownIdFields(raw, keyPath, brokenRefs, seenPaths);
+    }
+}
+function checkMapped(map, source, kind, path, brokenRefs, seenPaths) {
+    const values = idValues(source);
+    if (values.length === 0)
+        return;
+    seenPaths.add(path);
+    values.forEach((value, index) => {
+        if (map[value] !== undefined)
+            return;
+        brokenRefs.push({
+            path: values.length > 1 ? `${path}[${index}]` : path,
+            kind,
+            source: value,
+            message: `No target ${kind} mapping found for source ID ${value}`,
+        });
+    });
+}
+function checkAnyMapped(maps, source, kind, path, brokenRefs, seenPaths) {
+    const values = idValues(source);
+    if (values.length === 0)
+        return;
+    seenPaths.add(path);
+    values.forEach((value, index) => {
+        if (maps.some((map) => map[value] !== undefined))
+            return;
+        brokenRefs.push({
+            path: values.length > 1 ? `${path}[${index}]` : path,
+            kind,
+            source: value,
+            message: `No target ${kind} mapping found for source ID ${value}`,
+        });
+    });
+}
+function checkCustomObjectMapped(map, source, path, brokenRefs, seenPaths) {
+    const value = stringifyId(source);
+    if (!value || isStandardObjectTypeId(value))
+        return;
+    checkMapped(map, value, "customObject", path, brokenRefs, seenPaths);
+}
+function checkPipelineMapped(maps, source, path, brokenRefs, seenPaths) {
+    const values = idValues(source);
+    if (values.length === 0)
+        return;
+    seenPaths.add(path);
+    values.forEach((value, index) => {
+        const found = Object.keys(maps.pipelines).includes(value);
+        if (found)
+            return;
+        brokenRefs.push({
+            path: values.length > 1 ? `${path}[${index}]` : path,
+            kind: "pipeline",
+            source: value,
+            message: `No target pipeline mapping found for source ID ${value}`,
+        });
+    });
+}
+function checkStageMapped(maps, source, path, brokenRefs, seenPaths) {
+    const values = idValues(source);
+    if (values.length === 0)
+        return;
+    seenPaths.add(path);
+    values.forEach((value, index) => {
+        if (findPipelineStageTarget(maps.pipelines, value) !== undefined)
+            return;
+        brokenRefs.push({
+            path: values.length > 1 ? `${path}[${index}]` : path,
+            kind: "pipelineStage",
+            source: value,
+            message: `No target pipeline-stage mapping found for source ID ${value}`,
+        });
+    });
+}
+function normalizeWorkflows(input) {
+    if (Array.isArray(input))
+        return input.filter(record);
+    const root = record(input);
+    if (!root)
+        return [];
+    for (const key of ["results", "workflows", "flows"]) {
+        const candidate = root[key];
+        if (Array.isArray(candidate))
+            return candidate.filter(record);
+    }
+    return [root];
+}
+function idValues(raw) {
+    if (Array.isArray(raw))
+        return raw.map(stringifyId).filter((value) => value !== undefined);
+    const value = stringifyId(raw);
+    return value ? [value] : [];
+}
+function hasIdLikeValue(raw) {
+    if (Array.isArray(raw))
+        return raw.some(hasIdLikeValue);
+    return stringifyId(raw) !== undefined;
+}
+function records(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter(record);
+}
+function record(raw) {
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        return raw;
+    }
+    return undefined;
+}
+function stringField(record, key) {
+    const value = record[key];
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+//# sourceMappingURL=preflight.js.map

package/dist/commands/workflows/preflight.js.map

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

package/dist/core/action-contract.d.ts

@@ -0,0 +1,43 @@
+export declare const ACTION_CONTRACT_SCHEMA: "hscli.action-contract/v1";
+export interface ActionContractCommand {
+    argv: string[];
+    verifyArgv?: string[];
+    description?: string;
+}
+export interface ActionContractOperation {
+    summary: string;
+    commands: ActionContractCommand[];
+}
+export interface ActionContractLimits {
+    maxCommands?: number;
+    maxRecords?: number;
+}
+export interface ActionContractDraft {
+    profile: string;
+    portalId: string;
+    createdAt?: string;
+    expiresAt: string;
+    changeTicket?: string;
+    operation: ActionContractOperation;
+    limits?: ActionContractLimits;
+}
+export interface ActionContract extends ActionContractDraft {
+    schema: typeof ACTION_CONTRACT_SCHEMA;
+    id: string;
+    createdAt: string;
+    digest: string;
+}
+export interface ActionContractVerificationContext {
+    profile: string;
+    portalId?: string;
+    changeTicket?: string;
+    now?: Date;
+}
+export declare function readActionContractFile(path: string): unknown;
+export declare function sealActionContract(input: unknown, now?: Date): ActionContract;
+export declare function verifyActionContract(input: unknown, context: ActionContractVerificationContext): {
+    contract: ActionContract;
+    digest: string;
+    valid: true;
+    portalCheck: "matched" | "unavailable";
+};

package/dist/core/action-contract.js

@@ -0,0 +1,207 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { CliError, redactSensitive } from "./output.js";
+export const ACTION_CONTRACT_SCHEMA = "hscli.action-contract/v1";
+const FORBIDDEN_ROOT_COMMANDS = new Set(["agent", "auth", "help", "home", "internal", "mcp", "ui"]);
+const FORBIDDEN_GLOBAL_ARGS = new Set([
+    "--api-base-url",
+    "--change-ticket",
+    "--dry-run",
+    "--force",
+    "--hublet",
+    "--policy-file",
+    "--profile",
+    "--telemetry-file",
+]);
+export function readActionContractFile(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new CliError("ACTION_CONTRACT_FILE_INVALID", `Unable to read action contract '${path}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function sealActionContract(input, now = new Date()) {
+    const draft = parseDraft(input, now);
+    const unsigned = {
+        schema: ACTION_CONTRACT_SCHEMA,
+        ...draft,
+    };
+    rejectSensitiveData(unsigned);
+    const digest = digestValue(unsigned);
+    return {
+        ...unsigned,
+        id: `act_${digest.slice(0, 20)}`,
+        digest,
+    };
+}
+export function verifyActionContract(input, context) {
+    const contract = parseContract(input);
+    rejectSensitiveData(contract);
+    const { digest, id, ...unsigned } = contract;
+    const expectedDigest = digestValue(unsigned);
+    if (digest !== expectedDigest || id !== `act_${expectedDigest.slice(0, 20)}`) {
+        throw new CliError("ACTION_CONTRACT_DIGEST_MISMATCH", "Action contract digest or ID does not match its payload.");
+    }
+    if (contract.profile !== context.profile) {
+        throw new CliError("ACTION_CONTRACT_PROFILE_MISMATCH", `Contract profile '${contract.profile}' does not match active profile '${context.profile}'.`);
+    }
+    if (context.portalId && contract.portalId !== context.portalId) {
+        throw new CliError("ACTION_CONTRACT_PORTAL_MISMATCH", `Contract portal '${contract.portalId}' does not match active portal '${context.portalId}'.`);
+    }
+    if (context.changeTicket && contract.changeTicket !== context.changeTicket) {
+        throw new CliError("ACTION_CONTRACT_CHANGE_TICKET_MISMATCH", `Contract change ticket '${contract.changeTicket ?? "none"}' does not match active ticket '${context.changeTicket}'.`);
+    }
+    const now = context.now ?? new Date();
+    if (Date.parse(contract.expiresAt) <= now.getTime()) {
+        throw new CliError("ACTION_CONTRACT_EXPIRED", `Action contract expired at ${contract.expiresAt}.`);
+    }
+    return {
+        contract,
+        digest,
+        valid: true,
+        portalCheck: context.portalId ? "matched" : "unavailable",
+    };
+}
+function parseDraft(input, now) {
+    const value = requireRecord(input, "Action contract draft must be a JSON object.");
+    const profile = requireString(value.profile, "profile");
+    const portalId = requireString(value.portalId, "portalId");
+    const createdAt = normalizeTimestamp(value.createdAt ?? now.toISOString(), "createdAt");
+    const expiresAt = normalizeTimestamp(value.expiresAt, "expiresAt");
+    if (Date.parse(expiresAt) <= Date.parse(createdAt)) {
+        throw new CliError("ACTION_CONTRACT_TIME_INVALID", "expiresAt must be later than createdAt.");
+    }
+    const operation = parseOperation(value.operation);
+    const limits = parseLimits(value.limits);
+    const maxCommands = limits?.maxCommands ?? 25;
+    if (operation.commands.length > maxCommands) {
+        throw new CliError("ACTION_CONTRACT_COMMAND_LIMIT", `Contract contains ${operation.commands.length} commands; limit is ${maxCommands}.`);
+    }
+    return {
+        profile,
+        portalId,
+        createdAt,
+        expiresAt,
+        operation,
+        ...(value.changeTicket === undefined ? {} : { changeTicket: requireString(value.changeTicket, "changeTicket") }),
+        ...(limits ? { limits } : {}),
+    };
+}
+function parseContract(input) {
+    const value = requireRecord(input, "Action contract must be a JSON object.");
+    if (value.schema !== ACTION_CONTRACT_SCHEMA) {
+        throw new CliError("ACTION_CONTRACT_SCHEMA_UNSUPPORTED", `Expected schema '${ACTION_CONTRACT_SCHEMA}'.`);
+    }
+    const draft = parseDraft(value, new Date());
+    return {
+        schema: ACTION_CONTRACT_SCHEMA,
+        id: requireString(value.id, "id"),
+        digest: requireString(value.digest, "digest"),
+        ...draft,
+    };
+}
+function parseOperation(input) {
+    const value = requireRecord(input, "operation must be an object.");
+    const summary = requireString(value.summary, "operation.summary");
+    if (!Array.isArray(value.commands) || value.commands.length === 0) {
+        throw new CliError("ACTION_CONTRACT_OPERATION_INVALID", "operation.commands must contain at least one command.");
+    }
+    return {
+        summary,
+        commands: value.commands.map((command, index) => parseCommand(command, index)),
+    };
+}
+function parseCommand(input, index) {
+    const value = requireRecord(input, `operation.commands[${index}] must be an object.`);
+    const argv = parseArgv(value.argv, `operation.commands[${index}].argv`);
+    validateContractArgv(argv);
+    const verifyArgv = value.verifyArgv === undefined
+        ? undefined
+        : parseArgv(value.verifyArgv, `operation.commands[${index}].verifyArgv`);
+    if (verifyArgv)
+        validateContractArgv(verifyArgv);
+    return {
+        argv,
+        ...(verifyArgv ? { verifyArgv } : {}),
+        ...(value.description === undefined ? {} : { description: requireString(value.description, `operation.commands[${index}].description`) }),
+    };
+}
+function validateContractArgv(argv) {
+    const root = argv[0];
+    if (FORBIDDEN_ROOT_COMMANDS.has(root)) {
+        throw new CliError("ACTION_CONTRACT_COMMAND_FORBIDDEN", `Root command '${root}' is not allowed in action contracts.`);
+    }
+    for (const arg of argv) {
+        if (FORBIDDEN_GLOBAL_ARGS.has(arg)) {
+            throw new CliError("ACTION_CONTRACT_GLOBAL_ARG_FORBIDDEN", `Global argument '${arg}' must be supplied by the contract runner.`);
+        }
+    }
+}
+function parseArgv(input, field) {
+    if (!Array.isArray(input) || input.length === 0 || input.some((arg) => typeof arg !== "string" || !arg.trim())) {
+        throw new CliError("ACTION_CONTRACT_ARGV_INVALID", `${field} must be a non-empty array of non-empty strings.`);
+    }
+    const argv = input.map((arg) => String(arg));
+    if (argv.some((arg) => /[\0\r\n]/.test(arg))) {
+        throw new CliError("ACTION_CONTRACT_ARGV_INVALID", `${field} cannot contain NUL or line-break characters.`);
+    }
+    return argv;
+}
+function parseLimits(input) {
+    if (input === undefined)
+        return undefined;
+    const value = requireRecord(input, "limits must be an object.");
+    const output = {};
+    for (const field of ["maxCommands", "maxRecords"]) {
+        if (value[field] === undefined)
+            continue;
+        const parsed = Number(value[field]);
+        if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+            throw new CliError("ACTION_CONTRACT_LIMIT_INVALID", `limits.${field} must be a positive integer.`);
+        }
+        output[field] = parsed;
+    }
+    return output;
+}
+function requireRecord(input, message) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        throw new CliError("ACTION_CONTRACT_INVALID", message);
+    }
+    return input;
+}
+function requireString(input, field) {
+    if (typeof input !== "string" || !input.trim()) {
+        throw new CliError("ACTION_CONTRACT_INVALID", `${field} must be a non-empty string.`);
+    }
+    return input.trim();
+}
+function normalizeTimestamp(input, field) {
+    const value = requireString(input, field);
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp)) {
+        throw new CliError("ACTION_CONTRACT_TIME_INVALID", `${field} must be an ISO-8601 timestamp.`);
+    }
+    return new Date(timestamp).toISOString();
+}
+function rejectSensitiveData(input) {
+    if (canonicalize(input) !== canonicalize(redactSensitive(input))) {
+        throw new CliError("ACTION_CONTRACT_SENSITIVE_DATA", "Action contracts cannot contain credentials or sensitive values.");
+    }
+}
+function digestValue(input) {
+    return createHash("sha256").update(canonicalize(input)).digest("hex");
+}
+function canonicalize(input) {
+    if (Array.isArray(input))
+        return `[${input.map((item) => canonicalize(item)).join(",")}]`;
+    if (input && typeof input === "object") {
+        const record = input;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalize(record[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(input);
+}
+//# sourceMappingURL=action-contract.js.map

package/dist/core/action-contract.js.map

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

package/dist/core/auth.d.ts

@@ -1,8 +1,12 @@
 export interface AuthProfile {
     token: string;
+    authMode?: "private-app" | "oauth";
     refreshToken?: string;
     expiresAt?: string;
     scopes?: string[];
+    userId?: string;
+    oauthClientId?: string;
+    oauthClientSecretEnv?: string;
     portalId?: string;
     uiDomain?: string;
     dataHostingLocation?: string;
@@ -33,6 +37,8 @@ export declare function getHscliHomeDir(): string;
 export declare function saveToken(profile: string, token: string): void;
 export declare function saveProfile(profile: string, data: AuthProfile): void;
 export declare function getToken(profile: string): string;
+export declare function resolveAuthMode(profile: AuthProfile): "private-app" | "oauth";
+export declare function getValidAccessToken(profileName: string): Promise<string>;
 export declare function removeToken(profile: string): boolean;
 export declare function hasProfile(profile: string): boolean;
 export declare function listProfiles(): string[];