convex
Version:
Client for the Convex Cloud
499 lines (498 loc) • 19.6 kB
JavaScript
;
import { Command } from "@commander-js/extra-typings";
import { oneoffContext } from "../bundler/context.js";
import { chalkStderr } from "chalk";
import {
deploymentSelectionWithinProjectFromOptions,
fetchTeamAndProject,
getTeamAndProjectSlugForDeployment,
loadSelectedDeploymentCredentials
} from "./lib/api.js";
import { actionDescription } from "./lib/command.js";
import { ensureHasConvexDependency } from "./lib/utils/utils.js";
import { getDeploymentSelection } from "./lib/deploymentSelection.js";
import {
ensureWorkosEnvironmentProvisioned,
provisionWorkosTeamInteractive
} from "./lib/workos/workos.js";
import {
disconnectWorkOSTeam,
getCandidateEmailsForWorkIntegration,
getDeploymentCanProvisionWorkOSEnvironments,
getInvitationEligibleEmails,
getWorkosEnvironmentHealth,
getWorkosTeamHealth,
inviteToWorkosTeam,
listProjectWorkOSEnvironments,
createProjectWorkOSEnvironment,
deleteProjectWorkOSEnvironment
} from "./lib/workos/platformApi.js";
import {
logFinishedStep,
logMessage,
logWarning,
showSpinner,
stopSpinner
} from "../bundler/log.js";
import { readProjectConfig, getAuthKitConfig } from "./lib/config.js";
import { promptOptions, promptYesNo } from "./lib/utils/prompts.js";
async function selectEnvDeployment(options) {
const ctx = await oneoffContext(options);
const deploymentSelection = await getDeploymentSelection(ctx, options);
const selectionWithinProject = deploymentSelectionWithinProjectFromOptions(options);
const {
adminKey,
url: deploymentUrl,
deploymentFields
} = await loadSelectedDeploymentCredentials(
ctx,
deploymentSelection,
selectionWithinProject
);
if (!deploymentFields) {
return await ctx.crash({
exitCode: 1,
errorType: "fatal",
printedMessage: "WorkOS integration requires a configured deployment"
});
}
const deploymentNotice = ` (on ${chalkStderr.bold(deploymentFields.deploymentType)} deployment ${chalkStderr.bold(deploymentFields.deploymentName)})`;
const deploymentType = deploymentFields.deploymentType;
if (deploymentType === "custom") {
return await ctx.crash({
exitCode: 1,
errorType: "fatal",
printedMessage: `The WorkOS integration is not available for custom deployments yet.`
});
}
if (deploymentType !== "dev" && deploymentType !== "preview" && deploymentType !== "prod") {
return await ctx.crash({
exitCode: 1,
errorType: "fatal",
printedMessage: `The WorkOS integration is only available for cloud deployments (dev, preview, prod), not ${deploymentType}`
});
}
return {
ctx,
deployment: {
deploymentName: deploymentFields.deploymentName,
deploymentType,
deploymentUrl,
adminKey,
deploymentNotice
}
};
}
const workosTeamStatus = new Command("status").summary("Status of associated WorkOS team and environment").addDeploymentSelectionOptions(actionDescription("Check WorkOS status for")).action(async (_options, cmd) => {
const options = cmd.optsWithGlobals();
const { ctx, deployment } = await selectEnvDeployment(options);
const info = await fetchTeamAndProject(ctx, deployment.deploymentName);
const teamHealth = await getWorkosTeamHealth(ctx, info.teamId);
if (!teamHealth) {
logMessage(`WorkOS team: Not provisioned`);
const { availableEmails } = await getCandidateEmailsForWorkIntegration(ctx);
if (availableEmails.length > 0) {
logMessage(
` Verified emails that can provision: ${availableEmails.join(", ")}`
);
}
} else if (teamHealth.productionState === "inactive") {
logMessage(
`WorkOS team: ${teamHealth.name} (no credit card added on workos.com, so production auth environments cannot be created)`
);
} else {
logMessage(`WorkOS team: ${teamHealth.name}`);
}
const envHealth = await getWorkosEnvironmentHealth(
ctx,
deployment.deploymentName
);
if (!envHealth) {
logMessage(`WorkOS environment: Not provisioned`);
} else {
logMessage(`WorkOS environment: ${envHealth.name}`);
const workosUrl = `https://dashboard.workos.com/${envHealth.id}/authentication`;
logMessage(`${workosUrl}`);
}
try {
const { projectConfig } = await readProjectConfig(ctx);
const authKitConfig = await getAuthKitConfig(ctx, projectConfig);
if (!authKitConfig) {
logMessage(
`AuthKit config: ${chalkStderr.dim("Not configured in convex.json")}`
);
} else {
logMessage(`AuthKit config:`);
for (const deploymentType of ["dev", "preview", "prod"]) {
const envConfig = authKitConfig[deploymentType];
if (!envConfig) {
logMessage(
` ${deploymentType}: ${chalkStderr.dim("not configured")}`
);
continue;
}
let description = "";
if (deploymentType === "prod" && envConfig.environmentType) {
description = `environment type: ${envConfig.environmentType}`;
}
const configureStatus = envConfig.configure === false ? ", configure: disabled" : envConfig.configure ? ", will configure WorkOS" : "";
const localEnvVarsStatus = envConfig.localEnvVars === false ? "" : envConfig.localEnvVars ? `, ${Object.keys(envConfig.localEnvVars).length} local env vars` : "";
const configInfo = [description, configureStatus, localEnvVarsStatus].filter((s) => s).join("");
logMessage(` ${deploymentType}: ${configInfo || "configured"}`);
}
}
} catch (error) {
logMessage(
`AuthKit config: ${chalkStderr.yellow(`Error reading config: ${String(error)}`)}`
);
}
});
const workosProvisionEnvironment = new Command("provision-environment").summary("Provision a WorkOS environment").description(
"Create or get the WorkOS environment and API key for this deployment"
).configureHelp({ showGlobalOptions: true }).allowExcessArguments(false).addDeploymentSelectionOptions(
actionDescription("Provision WorkOS environment for")
).option(
"--name <name>",
"Custom name for the WorkOS environment (if not provided, uses deployment name)"
).action(async (_options, cmd) => {
const options = cmd.optsWithGlobals();
const { ctx, deployment } = await selectEnvDeployment(options);
await ensureHasConvexDependency(
ctx,
"integration workos provision-environment"
);
try {
const { projectConfig } = await readProjectConfig(ctx);
const authKitConfig = await getAuthKitConfig(ctx, projectConfig);
const config = authKitConfig || { dev: {} };
if (!authKitConfig) {
logWarning(
"Consider using the 'authKit' config in convex.json for automatic provisioning."
);
logMessage(
"Learn more at https://docs.convex.dev/auth/authkit/auto-provision"
);
logMessage("");
}
await ensureWorkosEnvironmentProvisioned(
ctx,
deployment.deploymentName,
deployment,
config,
deployment.deploymentType
);
} catch (error) {
await ctx.crash({
exitCode: 1,
errorType: "fatal",
errForSentry: error,
printedMessage: `Failed to provision WorkOS environment: ${String(error)}`
});
}
});
const workosProvisionTeam = new Command("provision-team").summary("Provision a WorkOS team for this Convex team").description(
"Create a WorkOS team and associate it with this Convex team. This enables automatic provisioning of WorkOS environments for deployments on this team."
).configureHelp({ showGlobalOptions: true }).allowExcessArguments(false).addDeploymentSelectionOptions(actionDescription("Provision WorkOS team for")).action(async (_options, cmd) => {
const options = cmd.optsWithGlobals();
const { ctx, deployment } = await selectEnvDeployment(options);
const { hasAssociatedWorkosTeam, teamId } = await getDeploymentCanProvisionWorkOSEnvironments(
ctx,
deployment.deploymentName
);
if (hasAssociatedWorkosTeam) {
logMessage(
chalkStderr.yellow(
"This Convex team already has an associated WorkOS team."
)
);
logMessage(
chalkStderr.dim(
"Use 'npx convex integration workos status' to view details."
)
);
return;
}
const result = await provisionWorkosTeamInteractive(
ctx,
deployment.deploymentName,
teamId,
deployment.deploymentType
);
if (!result.success) {
logMessage(chalkStderr.gray("Cancelled."));
return;
}
logMessage(
chalkStderr.green(
`
\u2713 Successfully created WorkOS team "${result.workosTeamName}" (${result.workosTeamId})`
)
);
logMessage(
chalkStderr.dim(
"You can now provision WorkOS environments for deployments on this team."
)
);
});
const workosDisconnectTeam = new Command("disconnect-team").summary("Disconnect WorkOS team from Convex team").description(
"Remove the associated WorkOS team from this Convex team. This is a destructive action that will prevent new WorkOS environments from being provisioned. Existing environments will continue to work with their current API keys."
).configureHelp({ showGlobalOptions: true }).allowExcessArguments(false).addDeploymentSelectionOptions(
actionDescription("Disconnect WorkOS team for")
).action(async (_options, cmd) => {
const options = cmd.optsWithGlobals();
const { ctx, deployment } = await selectEnvDeployment(options);
const { hasAssociatedWorkosTeam, teamId } = await getDeploymentCanProvisionWorkOSEnvironments(
ctx,
deployment.deploymentName
);
if (!hasAssociatedWorkosTeam) {
logMessage(
chalkStderr.yellow(
"This Convex team does not have an associated WorkOS team."
)
);
return;
}
const info = await getTeamAndProjectSlugForDeployment(ctx, {
deploymentName: deployment.deploymentName
});
logMessage(
chalkStderr.yellow(
`Warning: This will disconnect the WorkOS team from Convex team "${info?.teamSlug}".`
)
);
logMessage(
"AuthKit environments provisioned for Convex deployments on this team will no longer use this WorkOS team to provision environments."
);
logMessage(
chalkStderr.dim(
"Existing WorkOS environments will continue to work with their current API keys."
)
);
const confirmed = await promptYesNo(ctx, {
message: "Are you sure you want to disconnect this WorkOS team?",
default: false
});
if (!confirmed) {
logMessage(chalkStderr.gray("Cancelled."));
return;
}
const result = await disconnectWorkOSTeam(ctx, teamId);
if (!result.success) {
if (result.error === "not_associated") {
logMessage(
chalkStderr.yellow(
"This Convex team does not have an associated WorkOS team."
)
);
return;
}
return await ctx.crash({
exitCode: 1,
errorType: "fatal",
printedMessage: `Failed to disconnect WorkOS team: ${result.message}`
});
}
logFinishedStep(
`Successfully disconnected WorkOS team "${result.workosTeamName}" (${result.workosTeamId})`
);
});
const workosInvite = new Command("invite").summary("Invite yourself to the WorkOS team").description(
"Send an invitation to join the WorkOS team associated with your Convex team"
).option("--email <email>", "Email address to invite (skips validation)").configureHelp({ showGlobalOptions: true }).allowExcessArguments(false).addDeploymentSelectionOptions(
actionDescription("Invite yourself to WorkOS team for")
).action(async (options, cmd) => {
const allOptions = cmd.optsWithGlobals();
const { ctx, deployment } = await selectEnvDeployment(allOptions);
const info = await fetchTeamAndProject(ctx, deployment.deploymentName);
let emailToInvite;
if (options.email) {
emailToInvite = options.email;
} else {
const { eligibleEmails, adminEmail } = await getInvitationEligibleEmails(
ctx,
info.teamId
);
const allInvitableEmails = [...eligibleEmails];
if (adminEmail && !allInvitableEmails.includes(adminEmail)) {
allInvitableEmails.push(adminEmail);
}
if (allInvitableEmails.length === 0) {
logMessage(
"You don't have any verified emails available for invitation."
);
logMessage(
"This could be because all your verified emails are already admin of other WorkOS teams."
);
return;
}
emailToInvite = await promptOptions(ctx, {
message: "Which email would you like to invite to the WorkOS team?",
choices: allInvitableEmails.map((email) => ({
name: email + (email === adminEmail ? " (admin email)" : ""),
value: email
})),
default: allInvitableEmails[0]
});
const confirmed = await promptYesNo(ctx, {
message: `Send invitation to ${emailToInvite}?`,
default: true
});
if (!confirmed) {
logMessage("Invitation cancelled.");
return;
}
}
logMessage(`Sending invitation to ${emailToInvite}...`);
const result = await inviteToWorkosTeam(ctx, info.teamId, emailToInvite);
if (result.result === "success") {
logMessage(
`\u2713 Successfully sent invitation to ${result.email} with role ${result.roleSlug}`
);
logMessage(
"Check your email for the invitation link to join the WorkOS team."
);
} else if (result.result === "teamNotProvisioned") {
logMessage(
`\u2717 ${result.message}. Run 'npx convex integration workos provision-environment' first.`
);
} else if (result.result === "alreadyInWorkspace") {
logMessage(
`\u2717 ${result.message}. This usually means the email is already used in another WorkOS workspace.`
);
}
});
const workosProjectEnvList = new Command("list-project-environments").summary("List WorkOS environments for current project").description(
"List all WorkOS AuthKit environments created for the current project.\nThese environments can be used across multiple deployments."
).addDeploymentSelectionOptions(
actionDescription("List project environments for")
).action(async (_options, cmd) => {
const options = cmd.optsWithGlobals();
const { ctx, deployment } = await selectEnvDeployment(options);
const info = await fetchTeamAndProject(ctx, deployment.deploymentName);
logMessage("Fetching project WorkOS environments...");
try {
const environments = await listProjectWorkOSEnvironments(
ctx,
info.projectId
);
if (environments.length === 0) {
logMessage("No WorkOS environments found for this project.");
logMessage(
chalkStderr.gray(
"Create one with: npx convex integration workos create-project-environment --name <name>"
)
);
} else {
logMessage(chalkStderr.bold("WorkOS Project Environments:"));
for (const env of environments) {
const prodLabel = env.isProduction ? chalkStderr.yellow(" (production)") : "";
logMessage(
` ${chalkStderr.green(env.userEnvironmentName)}${prodLabel} - Client ID: ${env.workosClientId}`
);
}
}
} catch (error) {
logMessage(
chalkStderr.red(`Failed to list environments: ${String(error)}`)
);
}
});
const workosProjectEnvCreate = new Command("create-project-environment").summary("Create a new WorkOS environment for the project").description(
"Create a new WorkOS AuthKit environment for this project.\nThe environment can be used across multiple deployments."
).requiredOption("--name <name>", "Name for the new environment").option("--production", "Mark this environment as a production environment").addDeploymentSelectionOptions(
actionDescription("Create project environment for")
).action(async (_options, cmd) => {
const options = cmd.optsWithGlobals();
const environmentName = options.name;
const isProduction = options.production;
const { ctx, deployment } = await selectEnvDeployment(options);
const info = await fetchTeamAndProject(ctx, deployment.deploymentName);
showSpinner(
`Creating project-level WorkOS environment '${environmentName}'...`
);
try {
const response = await createProjectWorkOSEnvironment(
ctx,
info.projectId,
environmentName,
isProduction
);
stopSpinner();
logFinishedStep(`Created WorkOS environment '${environmentName}'`);
logMessage("");
logMessage(chalkStderr.bold("Environment Details:"));
logMessage(` Name: ${response.userEnvironmentName}`);
logMessage(` Client ID: ${response.workosClientId}`);
logMessage(` API Key: ${response.workosApiKey}`);
} catch (error) {
stopSpinner();
if (error?.message?.includes("NoWorkOSTeam")) {
logMessage(
chalkStderr.red(
"Your team doesn't have a WorkOS integration configured yet."
)
);
logMessage(
"Please run 'npx convex integration workos provision-team' first."
);
} else if (error?.message?.includes("duplicate")) {
logMessage(
chalkStderr.red(
`An environment named '${environmentName}' already exists for this project.`
)
);
} else if (error?.message?.includes("TooManyEnvironments")) {
logMessage(
chalkStderr.red(
"You've reached the limit of 10 WorkOS environments per project. If you need more, please contact support."
)
);
} else {
logMessage(chalkStderr.red(`Failed to create environment: ${error}`));
}
}
});
const workosProjectEnvDelete = new Command("delete-project-environment").summary("Delete a WorkOS environment from the project").description(
"Delete a WorkOS environment from this project.\nThis will permanently remove the environment and its credentials.\nUse the client ID shown in list-project-environments output."
).requiredOption(
"--client-id <clientId>",
"WorkOS client ID of the environment to delete (shown in list output)"
).addDeploymentSelectionOptions(
actionDescription("Delete project environment for")
).action(async (_options, cmd) => {
const options = cmd.optsWithGlobals();
const clientId = options.clientId;
const { ctx, deployment } = await selectEnvDeployment(options);
const info = await fetchTeamAndProject(ctx, deployment.deploymentName);
const confirmed = await promptYesNo(ctx, {
message: `Are you sure you want to delete environment with client ID '${clientId}'?`,
default: false
});
if (!confirmed) {
logMessage("Deletion cancelled.");
return;
}
showSpinner(
`Deleting project WorkOS environment (this can take a while)...`
);
try {
await deleteProjectWorkOSEnvironment(ctx, info.projectId, clientId);
stopSpinner();
logFinishedStep(`Deleted environment with client ID '${clientId}'`);
} catch (error) {
stopSpinner();
if (error?.message?.includes("not found")) {
logMessage(
chalkStderr.red(
`Environment with client ID '${clientId}' not found.`
)
);
} else {
logMessage(chalkStderr.red(`Failed to delete environment: ${error}`));
}
}
});
const workos = new Command("workos").summary("WorkOS integration commands").description("Manage WorkOS team provisioning and environment setup").addCommand(workosProvisionEnvironment).addCommand(workosTeamStatus).addCommand(workosProvisionTeam).addCommand(workosDisconnectTeam).addCommand(workosInvite).addCommand(workosProjectEnvList).addCommand(workosProjectEnvCreate).addCommand(workosProjectEnvDelete);
export const integration = new Command("integration").summary("Integration commands").description("Commands for managing third-party integrations").addCommand(workos);
//# sourceMappingURL=integration.js.map