@cursor/bdk 0.2.3 → 0.2.5

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

@@ -1,544 +0,0 @@
-/**
- * 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

@@ -1,11 +0,0 @@
-/**
- * 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

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