@cursor/bdk 0.2.1

package/src/internal/slack-provision-client.ts

@@ -0,0 +1,544 @@
+/**
+ * Thin client for the Slack provisioning API on the Cursor backend ("Add
+ * to Slack"). One control plane per hosted architecture:
+ * `/internal/agent-serve/slack` for `architecture: "v1"` and
+ * `/internal/agentsdk/slack` for `"v2"`. A client is pinned to one of them
+ * because the wizard session, its poll, the token storage, and the app
+ * inventory all live on that side. Pure request/response + error mapping —
+ * no console I/O, no polling loops; rendering lives in `cli-slack.ts`.
+ *
+ * Auth is the user API key sent directly as the bearer (the routes are
+ * `wrapUserApiRoute` on the backend); there is no token exchange here.
+ * The endpoints ride `requireAgentServeAccess` and 404 `{ error: "Not found" }`
+ * when Agent Serve is off — same mapping as other agent-sdk deploy 404s.
+ * Expected provisioning failures carry a stable JSON `code`
+ * (`not_connected`, `insufficient_scopes`, `manager_reauth_required`,
+ * `app_conflict`, `ratelimited`, `invalid_app_id`, …)
+ * which flows through on {@link SlackProvisionApiError.code} so the CLI
+ * can branch.
+ */
+
+import { z } from "zod";
+import type { AgentArchitecture } from "../types.js";
+
+export type SlackAppEnv = "dev" | "prod";
+
+/**
+ * Backend mount of the Slack control plane for each hosted architecture.
+ * The backend validates the pairing: the v2 routes reject a wizard mint or
+ * token storage that does not name `"v2"`, and the v1 routes reject one
+ * that names it.
+ */
+export function slackControlPlaneBasePath(architecture: AgentArchitecture): string {
+  return architecture === "v2" ? "/internal/agentsdk/slack" : "/internal/agent-serve/slack";
+}
+
+/** One manager-connected Slack workspace from `GET /status`. */
+export interface SlackConnectedWorkspace {
+  slackTeamId: string;
+  /** Workspace name; absent on older backends, null on pre-existing rows. */
+  slackTeamName?: string | null;
+  slackUserId: string;
+  connectedAt: string;
+}
+
+/** One provisioned managed Slack app from `GET /status` (no token material). */
+export interface SlackManagedAppInfo {
+  slackAppId: string;
+  slackTeamId: string;
+  slug: string;
+  env: string;
+  installStatus: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface SlackProvisionStatus {
+  workspaces: SlackConnectedWorkspace[];
+  apps: SlackManagedAppInfo[];
+}
+
+export type SlackAppIconContentType = "image/png" | "image/jpeg" | "image/gif";
+
+/** Icon source for `setAppIcon`: an https image URL or a base64 file. */
+export type SlackAppIconInput =
+  | { url: string }
+  | { base64: string; contentType: SlackAppIconContentType };
+
+/**
+ * Outcome of `POST /apps`. Credentials are returned exactly once and never
+ * persisted server-side — the caller owns storing them. `appToken` can be
+ * absent when Slack's install response omitted the app-level token.
+ * `oauthAuthorizeUrl` is Slack's request-approval / reminder page. Fresh
+ * creates mint it; updates return it when Slack (or a persisted row) has one.
+ */
+export type SlackAppProvisionResult =
+  | {
+      status: "installed";
+      appId: string;
+      botToken: string;
+      appToken?: string;
+      /** Present when the provision requested an icon (best-effort outcome). */
+      iconStatus?: "set" | "failed";
+    }
+  | {
+      status: "pending_admin_approval";
+      appId: string;
+      oauthAuthorizeUrl?: string;
+      iconStatus?: "set" | "failed";
+    };
+
+export class SlackProvisionApiError extends Error {
+  readonly status: number;
+  /** Stable backend error code (`not_connected`, `ratelimited`, …). */
+  readonly code?: string;
+  /** Seconds to wait before retrying (from 429 responses). */
+  readonly retryAfterSeconds?: number;
+  /** Drifted manifest paths (from `manifest_drift` 409 bodies). */
+  readonly changedPaths?: string[];
+
+  constructor(
+    message: string,
+    options: {
+      status: number;
+      code?: string;
+      retryAfterSeconds?: number;
+      changedPaths?: string[];
+    },
+  ) {
+    super(message);
+    this.name = "SlackProvisionApiError";
+    this.status = options.status;
+    this.code = options.code;
+    this.retryAfterSeconds = options.retryAfterSeconds;
+    this.changedPaths = options.changedPaths;
+  }
+}
+
+// ============================================================================
+// Response shapes (backend agentServeSlackEndpoints route bodies).
+// Interfaces are hand-written (the package compiles with
+// --isolatedDeclarations, so exported types cannot be z.infer of an
+// unannotated schema); the zod schemas below stay module-internal.
+// ============================================================================
+
+// All response schemas are `.passthrough()` so unknown fields from a newer
+// backend flow through untouched instead of breaking the parse.
+const statusResponseSchema = z
+  .object({
+    workspaces: z.array(
+      z
+        .object({
+          slackTeamId: z.string(),
+          slackTeamName: z.string().nullish(),
+          slackUserId: z.string(),
+          connectedAt: z.string(),
+        })
+        .passthrough(),
+    ),
+    apps: z.array(
+      z
+        .object({
+          slackAppId: z.string(),
+          slackTeamId: z.string(),
+          slug: z.string(),
+          env: z.string(),
+          installStatus: z.string(),
+          createdAt: z.string(),
+          updatedAt: z.string(),
+        })
+        .passthrough(),
+    ),
+  })
+  .passthrough();
+
+const connectResponseSchema = z
+  .object({
+    url: z.string().min(1),
+  })
+  .passthrough();
+
+const provisionResponseSchema = z.discriminatedUnion("status", [
+  z
+    .object({
+      status: z.literal("installed"),
+      appId: z.string(),
+      botToken: z.string(),
+      appToken: z.string().optional(),
+      iconStatus: z.enum(["set", "failed"]).optional(),
+    })
+    .passthrough(),
+  z
+    .object({
+      status: z.literal("pending_admin_approval"),
+      appId: z.string(),
+      oauthAuthorizeUrl: z.string().optional(),
+      iconStatus: z.enum(["set", "failed"]).optional(),
+    })
+    .passthrough(),
+]);
+
+const deleteResponseSchema = z
+  .object({
+    deleted: z.boolean(),
+  })
+  .passthrough();
+
+const setIconResponseSchema = z
+  .object({
+    ok: z.boolean(),
+  })
+  .passthrough();
+
+const mintWizardResponseSchema = z
+  .object({
+    wizardId: z.string().min(1),
+    url: z.string().min(1),
+  })
+  .passthrough();
+
+const wizardPollResponseSchema = z
+  .object({
+    wizardId: z.string(),
+    teamId: z.number(),
+    slug: z.string(),
+    env: z.string(),
+    status: z.string(),
+    appId: z.string().optional(),
+    oauthAuthorizeUrl: z.string().optional(),
+    approvalRequest: z.string().optional(),
+    error: z.string().optional(),
+    localEnv: z
+      .object({
+        botToken: z.string().min(1),
+        appToken: z.string().optional(),
+      })
+      .optional(),
+    localEnvClaimed: z.boolean().optional(),
+  })
+  .passthrough();
+
+export interface SlackWizardMintResult {
+  wizardId: string;
+  url: string;
+}
+
+export interface SlackWizardPollResult {
+  wizardId: string;
+  teamId: number;
+  slug: string;
+  env: string;
+  status: string;
+  appId?: string;
+  oauthAuthorizeUrl?: string;
+  /** "pending" means the admin-approval request is already in Slack's queue. */
+  approvalRequest?: string;
+  error?: string;
+  localEnv?: { botToken: string; appToken?: string };
+  localEnvClaimed?: boolean;
+}
+
+/**
+ * Wizard mint body minus `architecture`: the client stamps its own so the
+ * route and the session it opens can never disagree.
+ */
+export interface SlackWizardMintInput {
+  teamId: number;
+  slug: string;
+  env: SlackAppEnv;
+  envPrefix?: string;
+  name?: string;
+  gitRepoUrl?: string;
+  gitRef?: string;
+  agentPath?: string;
+  channelPosts?: boolean;
+  slackTeamId?: string;
+  iconUrl?: string;
+  force?: boolean;
+}
+
+// ============================================================================
+// Client
+// ============================================================================
+
+export interface AgentServeSlackClientOptions {
+  backendUrl: string;
+  apiKey: string;
+  /**
+   * Hosted architecture of the agent whose Slack app is being managed
+   * (`defineAgent({ architecture })`, `"v2"` when omitted). Selects the
+   * control plane; see {@link slackControlPlaneBasePath}.
+   */
+  architecture: AgentArchitecture;
+  /** Test seam; defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+export class AgentServeSlackClient {
+  readonly architecture: AgentArchitecture;
+  private readonly backendUrl: string;
+  private readonly basePath: string;
+  private readonly apiKey: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options: AgentServeSlackClientOptions) {
+    this.backendUrl = options.backendUrl.endsWith("/")
+      ? options.backendUrl.slice(0, -1)
+      : options.backendUrl;
+    this.architecture = options.architecture;
+    this.basePath = slackControlPlaneBasePath(options.architecture);
+    this.apiKey = options.apiKey;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+
+  /** Manager-connected workspaces + the managed-app inventory. */
+  async status(teamId: number): Promise<SlackProvisionStatus> {
+    const raw = await this.request({
+      method: "GET",
+      path: `${this.basePath}/status?teamId=${teamId}`,
+      context: { verb: "read Slack provisioning status" },
+    });
+    return statusResponseSchema.parse(raw);
+  }
+
+  /**
+   * Mint the browser consent URL for the Slack manager grant. After the
+   * user approves it, the workspace shows up in {@link status}.
+   */
+  async connect(teamId: number): Promise<string> {
+    const raw = await this.request({
+      method: "POST",
+      path: `${this.basePath}/connect`,
+      body: { teamId },
+      context: { verb: "start the Slack workspace connect" },
+    });
+    return connectResponseSchema.parse(raw).url;
+  }
+
+  /**
+   * Open a dashboard wizard session on this client's control plane. The
+   * session records the architecture, so the dashboard stores the minted
+   * tokens on the matching deployment and the poll below can find it.
+   */
+  async mintWizard(input: SlackWizardMintInput): Promise<SlackWizardMintResult> {
+    const raw = await this.request({
+      method: "POST",
+      path: `${this.basePath}/wizard`,
+      body: { ...input, architecture: this.architecture },
+      context: { verb: "start Slack setup" },
+    });
+    return mintWizardResponseSchema.parse(raw);
+  }
+
+  async pollWizard(wizardId: string): Promise<SlackWizardPollResult> {
+    const raw = await this.request({
+      method: "GET",
+      path: `${this.basePath}/wizard/${encodeURIComponent(wizardId)}`,
+      context: { verb: "poll Slack setup" },
+    });
+    return wizardPollResponseSchema.parse(raw);
+  }
+
+  /**
+   * Provision (create or update) and install one managed Slack app for
+   * (slackTeamId, slug, env). Expected failures throw
+   * {@link SlackProvisionApiError} with a stable `code`.
+   */
+  async provisionApp(args: {
+    teamId: number;
+    slackTeamId: string;
+    slug: string;
+    env: SlackAppEnv;
+    /** Full Slack app manifest JSON string. */
+    manifest: string;
+    /** Icon URL, applied best-effort by the backend after the install. */
+    icon?: { url: string };
+    /** Overwrite manifest edits made in Slack (skips the drift check). */
+    force?: boolean;
+  }): Promise<SlackAppProvisionResult> {
+    const raw = await this.request({
+      method: "POST",
+      path: `${this.basePath}/apps`,
+      body: {
+        teamId: args.teamId,
+        slackTeamId: args.slackTeamId,
+        slug: args.slug,
+        env: args.env,
+        manifest: args.manifest,
+        icon: args.icon,
+        force: args.force,
+      },
+      context: { verb: "provision the Slack app" },
+    });
+    return provisionResponseSchema.parse(raw);
+  }
+
+  /** Delete the Slack app and its inventory row. */
+  async deleteApp(args: { teamId: number; slackAppId: string }): Promise<void> {
+    const raw = await this.request({
+      method: "DELETE",
+      path: `${this.basePath}/apps/${encodeURIComponent(args.slackAppId)}?teamId=${args.teamId}`,
+      context: { verb: "delete the Slack app" },
+    });
+    deleteResponseSchema.parse(raw);
+  }
+
+  /** Set the app's icon: an https image URL or a base64 png/jpeg/gif ≤512KB. */
+  async setAppIcon(args: {
+    teamId: number;
+    slackAppId: string;
+    icon: SlackAppIconInput;
+  }): Promise<void> {
+    const raw = await this.request({
+      method: "POST",
+      path: `${this.basePath}/apps/${encodeURIComponent(args.slackAppId)}/icon`,
+      body: { teamId: args.teamId, icon: args.icon },
+      context: { verb: "set the Slack app icon" },
+    });
+    setIconResponseSchema.parse(raw);
+  }
+
+  private async request(args: {
+    method: "GET" | "POST" | "DELETE";
+    path: string;
+    body?: unknown;
+    context: { verb: string };
+  }): Promise<unknown> {
+    const headers: Record<string, string> = {
+      accept: "application/json",
+      authorization: `Bearer ${this.apiKey}`,
+    };
+    if (args.body !== undefined) {
+      headers["content-type"] = "application/json";
+    }
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${this.backendUrl}${args.path}`, {
+        method: args.method,
+        headers,
+        body: args.body === undefined ? undefined : JSON.stringify(args.body),
+        signal: AbortSignal.timeout(60_000),
+      });
+    } catch (error) {
+      throw new SlackProvisionApiError(
+        `Could not reach the Cursor backend at ${this.backendUrl}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        { status: 0 },
+      );
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      throw mapErrorResponse(response, text, args.context);
+    }
+    try {
+      return JSON.parse(text) as unknown;
+    } catch {
+      throw new SlackProvisionApiError(
+        `The Cursor backend returned a non-JSON response to ${args.context.verb}.`,
+        { status: response.status },
+      );
+    }
+  }
+}
+
+// ============================================================================
+// Error mapping (HTTP → actionable human messages, stable codes kept)
+// ============================================================================
+
+function parseErrorBody(bodyText: string): {
+  error?: string;
+  code?: string;
+  retryAfterSeconds?: number;
+  changedPaths?: string[];
+} {
+  let parsed: {
+    error?: unknown;
+    code?: unknown;
+    retryAfterSeconds?: unknown;
+    changedPaths?: unknown;
+  };
+  try {
+    parsed = JSON.parse(bodyText) as typeof parsed;
+  } catch {
+    return {};
+  }
+  return {
+    error: typeof parsed.error === "string" && parsed.error !== "" ? parsed.error : undefined,
+    code: typeof parsed.code === "string" && parsed.code !== "" ? parsed.code : undefined,
+    retryAfterSeconds:
+      typeof parsed.retryAfterSeconds === "number" ? parsed.retryAfterSeconds : undefined,
+    changedPaths:
+      Array.isArray(parsed.changedPaths) &&
+      parsed.changedPaths.every((path): path is string => typeof path === "string")
+        ? parsed.changedPaths
+        : undefined,
+  };
+}
+
+function mapErrorResponse(
+  response: Response,
+  bodyText: string,
+  context: { verb: string },
+): SlackProvisionApiError {
+  const body = parseErrorBody(bodyText);
+  const serverError = body.error;
+  switch (response.status) {
+    case 401:
+      return new SlackProvisionApiError(
+        "The Cursor API key was rejected. Run `agent-sdk login` again or update CURSOR_API_KEY.",
+        { status: 401 },
+      );
+    case 403:
+      return new SlackProvisionApiError(serverError ?? "Not authorized for this team", {
+        status: 403,
+      });
+    case 404: {
+      // Fastify's route-not-found envelope means we hit the wrong host
+      // (api2 vs api.cursor.com), not a closed gate.
+      if (/Route \S+ not found/i.test(bodyText)) {
+        return new SlackProvisionApiError(
+          `Agent Serve Slack API not found on this host — use the default api.cursor.com (unset CURSOR_API_BASE_URL), or point CURSOR_API_BASE_URL at a backend that mounts /internal/agent-serve/* and /internal/agentsdk/*.`,
+          { status: 404 },
+        );
+      }
+      // `{ error: "Not found" }` is Agent Serve off (`requireAgentServeAccess`),
+      // not a Slack-only enrollment bar.
+      if (serverError !== undefined && serverError !== "Not found") {
+        return new SlackProvisionApiError(serverError, {
+          status: 404,
+          code: body.code,
+        });
+      }
+      return new SlackProvisionApiError(
+        `Not found — the agent_serve_mvp feature gate may not be enabled for your team.`,
+        { status: 404 },
+      );
+    }
+    case 429: {
+      const retryAfterHeader = response.headers.get("retry-after");
+      const retryAfterSeconds =
+        retryAfterHeader !== null && /^\d+$/.test(retryAfterHeader)
+          ? Number(retryAfterHeader)
+          : body.retryAfterSeconds;
+      return new SlackProvisionApiError(
+        `${serverError ?? "Rate limited"}${
+          retryAfterSeconds === undefined ? "" : ` — retry in ${retryAfterSeconds}s`
+        }`,
+        { status: 429, code: body.code ?? "ratelimited", retryAfterSeconds },
+      );
+    }
+    default:
+      return new SlackProvisionApiError(
+        serverError ??
+          `The ${context.verb} request failed (${response.status}): ${
+            bodyText.slice(0, 300) || "(empty body)"
+          }`,
+        {
+          status: response.status,
+          code: body.code,
+          changedPaths: body.changedPaths,
+        },
+      );
+  }
+}

package/src/internal/slack-thread-key.ts

@@ -0,0 +1,11 @@
+/**
+ * Slack IM ids are `D…`. Those conversations are the channel, not a thread.
+ * Channel mentions stay `{channelId}:{threadTs}`.
+ */
+export function isSlackImChannel(channelId: string): boolean {
+  return channelId.startsWith("D");
+}
+
+export function slackThreadKey(channelId: string, threadTs: string): string {
+  return isSlackImChannel(channelId) ? channelId : `${channelId}:${threadTs}`;
+}

package/src/internal/sleep.ts

@@ -0,0 +1,3 @@
+export function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}