@cursor/july 0.1.16 → 0.1.17

package/dist/internal/slack-provision-client.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Thin client for the Agent Serve Slack provisioning API
+ * (`/internal/agent-serve/slack` on the Cursor backend — "Add to Slack").
+ * 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 are gated on the `agent_serve_slack_provisioning` Statsig
+ * gate and 404 when it is off — the error mapping says so instead of
+ * "not found". Expected provisioning failures carry a stable JSON `code`
+ * (`not_connected`, `insufficient_scopes`, `app_conflict`,
+ * `app_cap_reached`, `ratelimited`, `invalid_app_id`, …) which flows
+ * through on {@link SlackProvisionApiError.code} so the CLI can branch.
+ */
+export type SlackAppEnv = "dev" | "prod";
+/** One manager-connected Slack workspace from `GET /status`. */
+export interface SlackConnectedWorkspace {
+    slackTeamId: string;
+    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 only minted on a fresh app create, so an update
+ * that lands in admin approval omits it.
+ */
+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 declare 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[];
+    });
+}
+export interface AgentServeSlackClientOptions {
+    backendUrl: string;
+    apiKey: string;
+    /** Test seam; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export declare class AgentServeSlackClient {
+    private readonly backendUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    constructor(options: AgentServeSlackClientOptions);
+    /** Manager-connected workspaces + the managed-app inventory. */
+    status(teamId: number): Promise<SlackProvisionStatus>;
+    /**
+     * Mint the browser consent URL for the Slack manager grant. After the
+     * user approves it, the workspace shows up in {@link status}.
+     */
+    connect(teamId: number): Promise<string>;
+    /**
+     * Provision (create or update) and install one managed Slack app for
+     * (slackTeamId, slug, env). Expected failures throw
+     * {@link SlackProvisionApiError} with a stable `code`.
+     */
+    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>;
+    /** Delete the Slack app and its inventory row. */
+    deleteApp(args: {
+        teamId: number;
+        slackAppId: string;
+    }): Promise<void>;
+    /** Set the app's icon: an https image URL or a base64 png/jpeg/gif ≤512KB. */
+    setAppIcon(args: {
+        teamId: number;
+        slackAppId: string;
+        icon: SlackAppIconInput;
+    }): Promise<void>;
+    private request;
+}
+//# sourceMappingURL=slack-provision-client.d.ts.map

package/dist/internal/slack-provision-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack-provision-client.d.ts","sourceRoot":"","sources":["../../src/internal/slack-provision-client.ts"],"names":[],"mappings":"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"}

package/dist/internal/slack-provision-client.js

@@ -0,0 +1,284 @@
+/**
+ * Thin client for the Agent Serve Slack provisioning API
+ * (`/internal/agent-serve/slack` on the Cursor backend — "Add to Slack").
+ * 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 are gated on the `agent_serve_slack_provisioning` Statsig
+ * gate and 404 when it is off — the error mapping says so instead of
+ * "not found". Expected provisioning failures carry a stable JSON `code`
+ * (`not_connected`, `insufficient_scopes`, `app_conflict`,
+ * `app_cap_reached`, `ratelimited`, `invalid_app_id`, …) which flows
+ * through on {@link SlackProvisionApiError.code} so the CLI can branch.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { z } from "zod";
+export class SlackProvisionApiError extends Error {
+    constructor(message, options) {
+        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(),
+        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();
+export class AgentServeSlackClient {
+    constructor(options) {
+        var _a;
+        this.backendUrl = options.backendUrl.endsWith("/")
+            ? options.backendUrl.slice(0, -1)
+            : options.backendUrl;
+        this.apiKey = options.apiKey;
+        this.fetchImpl = (_a = options.fetchImpl) !== null && _a !== void 0 ? _a : fetch;
+    }
+    /** Manager-connected workspaces + the managed-app inventory. */
+    status(teamId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield this.request({
+                method: "GET",
+                path: `/internal/agent-serve/slack/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}.
+     */
+    connect(teamId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield this.request({
+                method: "POST",
+                path: "/internal/agent-serve/slack/connect",
+                body: { teamId },
+                context: { verb: "start the Slack workspace connect" },
+            });
+            return connectResponseSchema.parse(raw).url;
+        });
+    }
+    /**
+     * Provision (create or update) and install one managed Slack app for
+     * (slackTeamId, slug, env). Expected failures throw
+     * {@link SlackProvisionApiError} with a stable `code`.
+     */
+    provisionApp(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield this.request({
+                method: "POST",
+                path: "/internal/agent-serve/slack/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. */
+    deleteApp(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield this.request({
+                method: "DELETE",
+                path: `/internal/agent-serve/slack/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. */
+    setAppIcon(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield this.request({
+                method: "POST",
+                path: `/internal/agent-serve/slack/apps/${encodeURIComponent(args.slackAppId)}/icon`,
+                body: { teamId: args.teamId, icon: args.icon },
+                context: { verb: "set the Slack app icon" },
+            });
+            setIconResponseSchema.parse(raw);
+        });
+    }
+    request(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const headers = {
+                accept: "application/json",
+                authorization: `Bearer ${this.apiKey}`,
+            };
+            if (args.body !== undefined) {
+                headers["content-type"] = "application/json";
+            }
+            let response;
+            try {
+                response = yield this.fetchImpl(`${this.backendUrl}${args.path}`, {
+                    method: args.method,
+                    headers,
+                    body: args.body === undefined ? undefined : JSON.stringify(args.body),
+                    signal: AbortSignal.timeout(60000),
+                });
+            }
+            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 = yield response.text();
+            if (!response.ok) {
+                throw mapErrorResponse(response, text, args.context);
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch (_a) {
+                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) {
+    let parsed;
+    try {
+        parsed = JSON.parse(bodyText);
+    }
+    catch (_a) {
+        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) => typeof path === "string")
+            ? parsed.changedPaths
+            : undefined,
+    };
+}
+function mapErrorResponse(response, bodyText, context) {
+    var _a;
+    const body = parseErrorBody(bodyText);
+    const serverError = body.error;
+    switch (response.status) {
+        case 401:
+            return new SlackProvisionApiError("The Cursor API key was rejected. Run `agentkit login` again or update CURSOR_API_KEY.", { status: 401 });
+        case 403:
+            return new SlackProvisionApiError(`${serverError !== null && serverError !== void 0 ? serverError : "Not authorized"} — Slack provisioning needs team-admin permission and the cloud-agent entitlement on that 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/*.`, { status: 404 });
+            }
+            // The gate-off body is exactly {error: "Not found"}; anything else
+            // (e.g. "App not found" on delete) is a real not-found to surface.
+            if (serverError !== undefined && serverError !== "Not found") {
+                return new SlackProvisionApiError(serverError, {
+                    status: 404,
+                    code: body.code,
+                });
+            }
+            return new SlackProvisionApiError(`Not found — Cursor's "Add to Slack" provisioning (the agent_serve_slack_provisioning feature gate) is not enabled for this account yet.`, { 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 !== null && serverError !== void 0 ? serverError : "Rate limited"}${retryAfterSeconds === undefined
+                ? ""
+                : ` — retry in ${retryAfterSeconds}s`}`, { status: 429, code: (_a = body.code) !== null && _a !== void 0 ? _a : "ratelimited", retryAfterSeconds });
+        }
+        default:
+            return new SlackProvisionApiError(serverError !== null && serverError !== void 0 ? serverError : `The ${context.verb} request failed (${response.status}): ${bodyText.slice(0, 300) || "(empty body)"}`, {
+                status: response.status,
+                code: body.code,
+                changedPaths: body.changedPaths,
+            });
+    }
+}