@planescrm/sdk 0.2.0 → 0.4.0

package/dist/index.mjs

@@ -1,62 +1,74 @@
 // src/config.ts
+var MemoryTokenStorage = class {
+  constructor(seed) {
+    this.tokens = seed ?? null;
+  }
+  async getTokens() {
+    return this.tokens;
+  }
+  async setTokens(tokens) {
+    this.tokens = tokens;
+  }
+};
 var DEFAULT_BASE_URL = "https://api.planescrm.com/api/v1";
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_TOKEN_REFRESH_SKEW_MS = 6e4;
 
 // src/errors.ts
-var BlueprintError = class extends Error {
+var PlanesError = class extends Error {
   constructor(message, status, code) {
     super(message);
-    this.name = "BlueprintError";
+    this.name = "PlanesError";
     this.status = status;
     this.code = code;
   }
 };
-var AuthenticationError = class extends BlueprintError {
+var AuthenticationError = class extends PlanesError {
   constructor(message = "Authentication failed") {
     super(message, 401, "authentication_error");
     this.name = "AuthenticationError";
   }
 };
-var AuthorizationError = class extends BlueprintError {
+var AuthorizationError = class extends PlanesError {
   constructor(message = "Insufficient permissions") {
     super(message, 403, "authorization_error");
     this.name = "AuthorizationError";
   }
 };
-var NotFoundError = class extends BlueprintError {
+var NotFoundError = class extends PlanesError {
   constructor(message = "Resource not found") {
     super(message, 404, "not_found");
     this.name = "NotFoundError";
   }
 };
-var ValidationError = class extends BlueprintError {
+var ValidationError = class extends PlanesError {
   constructor(message = "Validation failed", fieldErrors = []) {
     super(message, 400, "validation_error");
     this.name = "ValidationError";
     this.fieldErrors = fieldErrors;
   }
 };
-var RateLimitError = class extends BlueprintError {
+var RateLimitError = class extends PlanesError {
   constructor(retryAfter = 1, message = "Rate limit exceeded") {
     super(message, 429, "rate_limit_error");
     this.name = "RateLimitError";
     this.retryAfter = retryAfter;
   }
 };
-var ServerError = class extends BlueprintError {
+var ServerError = class extends PlanesError {
   constructor(message = "Internal server error") {
     super(message, 500, "server_error");
     this.name = "ServerError";
   }
 };
-var WebhookVerificationError = class extends BlueprintError {
+var WebhookVerificationError = class extends PlanesError {
   constructor(message = "Webhook signature verification failed") {
     super(message, 400, "webhook_verification_error");
     this.name = "WebhookVerificationError";
   }
 };
-var OAuthError = class extends BlueprintError {
+var OAuthError = class extends PlanesError {
   constructor(errorCode, message = "OAuth error") {
     super(message, 400, "oauth_error");
     this.name = "OAuthError";
@@ -64,6 +76,87 @@ var OAuthError = class extends BlueprintError {
   }
 };
 
+// src/oauth.ts
+import { randomBytes } from "crypto";
+function buildAuthorizeUrl(options) {
+  const state = options.state ?? randomBytes(16).toString("hex");
+  const baseUrl = options.baseUrl.replace(/\/+$/, "");
+  const url = new URL(`${baseUrl}/oauth/authorize`);
+  url.searchParams.set("client_id", options.clientId);
+  url.searchParams.set("redirect_uri", options.redirectUri);
+  url.searchParams.set("scope", options.scopes.join(" "));
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("state", state);
+  return url.toString();
+}
+async function exchangeCode(options) {
+  const baseUrl = options.baseUrl.replace(/\/+$/, "");
+  const url = `${baseUrl}/oauth/token`;
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    client_id: options.clientId,
+    client_secret: options.clientSecret,
+    code: options.code,
+    redirect_uri: options.redirectUri
+  });
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString()
+  });
+  if (!response.ok) {
+    const errorBody = await response.json().catch(() => ({}));
+    const errorCode = errorBody["error"] ?? "unknown_error";
+    const errorDescription = errorBody["error_description"] ?? "Token exchange failed";
+    throw new OAuthError(errorCode, errorDescription);
+  }
+  return await response.json();
+}
+async function refreshAccessToken(options) {
+  const baseUrl = options.baseUrl.replace(/\/+$/, "");
+  const url = `${baseUrl}/oauth/token`;
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    client_id: options.clientId,
+    client_secret: options.clientSecret,
+    refresh_token: options.refreshToken
+  });
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString()
+  });
+  if (!response.ok) {
+    const errorBody = await response.json().catch(() => ({}));
+    const errorCode = errorBody["error"] ?? "unknown_error";
+    const errorDescription = errorBody["error_description"] ?? "Token refresh failed";
+    throw new OAuthError(errorCode, errorDescription);
+  }
+  return await response.json();
+}
+async function clientCredentialsGrant(options) {
+  const baseUrl = options.baseUrl.replace(/\/+$/, "");
+  const url = `${baseUrl}/oauth/token`;
+  const body = new URLSearchParams({
+    grant_type: "client_credentials",
+    client_id: options.clientId,
+    client_secret: options.clientSecret,
+    scope: options.scopes.join(" ")
+  });
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString()
+  });
+  if (!response.ok) {
+    const errorBody = await response.json().catch(() => ({}));
+    const errorCode = errorBody["error"] ?? "unknown_error";
+    const errorDescription = errorBody["error_description"] ?? "Client credentials grant failed";
+    throw new OAuthError(errorCode, errorDescription);
+  }
+  return await response.json();
+}
+
 // src/http.ts
 var HttpClient = class {
   constructor(config) {
@@ -73,24 +166,35 @@ var HttpClient = class {
     this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
     this.retryOnRateLimit = config.retryOnRateLimit !== false;
     this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    if (config.clientId && config.clientSecret) {
+      this.oauth = {
+        clientId: config.clientId,
+        clientSecret: config.clientSecret,
+        tokenStorage: config.tokenStorage ?? new MemoryTokenStorage(),
+        skewMs: config.tokenRefreshSkewMs ?? DEFAULT_TOKEN_REFRESH_SKEW_MS,
+        scopes: config.scopes
+      };
+    }
   }
   async request(options) {
     const url = this.buildUrl(options.path, options.params);
-    const headers = {
-      "Content-Type": "application/json",
-      ...this.getAuthHeaders(),
-      ...options.headers
-    };
-    const fetchOptions = {
-      method: options.method,
-      headers,
-      signal: AbortSignal.timeout(this.timeout)
-    };
-    if (options.body !== void 0) {
-      fetchOptions.body = JSON.stringify(options.body);
-    }
+    const bodyStr = options.body !== void 0 ? JSON.stringify(options.body) : void 0;
     let lastError;
+    let didRefreshOn401 = false;
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const headers = {
+        "Content-Type": "application/json",
+        ...await this.resolveAuthHeaders(),
+        ...options.headers
+      };
+      const fetchOptions = {
+        method: options.method,
+        headers,
+        signal: AbortSignal.timeout(this.timeout)
+      };
+      if (bodyStr !== void 0) {
+        fetchOptions.body = bodyStr;
+      }
       const response = await fetch(url, fetchOptions);
       if (response.ok) {
         if (response.status === 204) {
@@ -103,6 +207,12 @@ var HttpClient = class {
         await this.sleep(retryAfter * 1e3);
         continue;
       }
+      if (response.status === 401 && this.oauth && !didRefreshOn401) {
+        didRefreshOn401 = true;
+        await this.refreshTokens();
+        attempt--;
+        continue;
+      }
       lastError = await this.mapError(response);
       if (response.status !== 429 || !this.retryOnRateLimit) {
         throw lastError;
@@ -119,6 +229,76 @@ var HttpClient = class {
     }
     return {};
   }
+  /**
+   * Resolve the Authorization header for the current request. For the static
+   * accessToken/apiKey modes this is {@link getAuthHeaders}. For the
+   * OAuth-managed path it reads the stored token, proactively refreshing when
+   * the token is within the skew window of expiry.
+   */
+  async resolveAuthHeaders() {
+    if (!this.oauth) {
+      return this.getAuthHeaders();
+    }
+    const tokens = await this.oauth.tokenStorage.getTokens();
+    if (!tokens) {
+      return {};
+    }
+    if (tokens.expiresAt - Date.now() <= this.oauth.skewMs) {
+      const refreshed = await this.refreshTokens();
+      return { Authorization: `Bearer ${refreshed.accessToken}` };
+    }
+    return { Authorization: `Bearer ${tokens.accessToken}` };
+  }
+  /**
+   * Refresh the OAuth access token via `refreshAccessToken` and persist the new
+   * tokens through the configured {@link TokenStorage}. Concurrent callers share
+   * a single in-flight refresh.
+   */
+  async refreshTokens() {
+    if (!this.oauth) {
+      throw new AuthenticationError("Token refresh requires the OAuth clientId/clientSecret path");
+    }
+    if (this.refreshInFlight) {
+      return this.refreshInFlight;
+    }
+    const oauth = this.oauth;
+    this.refreshInFlight = (async () => {
+      const current = await oauth.tokenStorage.getTokens();
+      if (!current?.refreshToken) {
+        const response2 = await clientCredentialsGrant({
+          baseUrl: this.baseUrl,
+          clientId: oauth.clientId,
+          clientSecret: oauth.clientSecret,
+          scopes: oauth.scopes ?? []
+        });
+        const next2 = {
+          accessToken: response2.access_token,
+          refreshToken: response2.refresh_token ?? null,
+          expiresAt: Date.now() + response2.expires_in * 1e3
+        };
+        await oauth.tokenStorage.setTokens(next2);
+        return next2;
+      }
+      const response = await refreshAccessToken({
+        baseUrl: this.baseUrl,
+        clientId: oauth.clientId,
+        clientSecret: oauth.clientSecret,
+        refreshToken: current.refreshToken
+      });
+      const next = {
+        accessToken: response.access_token,
+        refreshToken: response.refresh_token || current.refreshToken,
+        expiresAt: Date.now() + response.expires_in * 1e3
+      };
+      await oauth.tokenStorage.setTokens(next);
+      return next;
+    })();
+    try {
+      return await this.refreshInFlight;
+    } finally {
+      this.refreshInFlight = void 0;
+    }
+  }
   buildUrl(path, params) {
     const url = new URL(`${this.baseUrl}${path}`);
     if (params) {
@@ -166,7 +346,7 @@ var HttpClient = class {
         if (response.status >= 500) {
           return new ServerError(message);
         }
-        return new BlueprintError(message, response.status, "unknown_error");
+        return new PlanesError(message, response.status, "unknown_error");
     }
   }
   sleep(ms) {
@@ -293,14 +473,207 @@ var InventoryResource = class extends BaseResource {
   }
 };
 
+// src/resources/contacts.ts
+var ContactChannelResource = class {
+  constructor(http2, contactId) {
+    this.http = http2;
+    this.basePath = `/contacts/${contactId}/channels`;
+  }
+  /** Returns `{ channel, duplicateOf }` — `duplicateOf` is the dedup signal. */
+  async create(data) {
+    return this.http.request({
+      method: "POST",
+      path: this.basePath,
+      body: data
+    });
+  }
+  async update(channelId, data) {
+    return this.http.request({
+      method: "PATCH",
+      path: `${this.basePath}/${channelId}`,
+      body: data
+    });
+  }
+  async delete(channelId) {
+    await this.http.request({
+      method: "DELETE",
+      path: `${this.basePath}/${channelId}`
+    });
+  }
+};
+var ContactResource = class extends BaseResource {
+  constructor(http2) {
+    super(http2, "/contacts");
+  }
+  async merge(winnerId, loserId) {
+    return this.http.request({
+      method: "POST",
+      path: `/contacts/${winnerId}/merge/${loserId}`
+    });
+  }
+  channels(contactId) {
+    return new ContactChannelResource(this.http, contactId);
+  }
+};
+
+// src/resources/activities.ts
+var ActivityResource = class {
+  constructor(http2) {
+    this.http = http2;
+  }
+  async create(data) {
+    return this.http.request({
+      method: "POST",
+      path: "/activities",
+      body: data
+    });
+  }
+  async list(params) {
+    return this.http.request({
+      method: "GET",
+      path: "/activities",
+      params
+    });
+  }
+  async listForEntity(entityType, entityId, params) {
+    return this.http.request({
+      method: "GET",
+      path: `/${entityType}/${entityId}/activities`,
+      params
+    });
+  }
+};
+
+// src/resources/tags.ts
+var TagResource = class extends BaseResource {
+  constructor(http2) {
+    super(http2, "/tags");
+  }
+  /** `TagsService.setEntityTags()` returns the final tag set wrapped in `{ tags }`. */
+  async setEntityTags(entityType, entityId, data) {
+    return this.http.request({
+      method: "PUT",
+      path: `/entities/${entityType}/${entityId}/tags`,
+      body: data
+    });
+  }
+  async getEntityTags(entityType, entityId) {
+    return this.http.request({
+      method: "GET",
+      path: `/entities/${entityType}/${entityId}/tags`
+    });
+  }
+  async getEntities(tagId, params) {
+    return this.http.request({
+      method: "GET",
+      path: `/tags/${tagId}/entities`,
+      params
+    });
+  }
+};
+
+// src/webhooks.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function verifyWebhookSignature(payload, signature, secret) {
+  if (!signature || !secret || !payload) {
+    return false;
+  }
+  const prefix = "sha256=";
+  if (!signature.startsWith(prefix)) {
+    return false;
+  }
+  const receivedHex = signature.slice(prefix.length);
+  if (!receivedHex) {
+    return false;
+  }
+  const expectedHmac = createHmac("sha256", secret).update(payload).digest("hex");
+  const receivedBuf = Buffer.from(receivedHex, "hex");
+  const expectedBuf = Buffer.from(expectedHmac, "hex");
+  if (receivedBuf.length !== expectedBuf.length) {
+    return false;
+  }
+  return timingSafeEqual(receivedBuf, expectedBuf);
+}
+function parseWebhookEvent(body, signature, secret) {
+  if (!verifyWebhookSignature(body, signature, secret)) {
+    throw new WebhookVerificationError();
+  }
+  return JSON.parse(body);
+}
+
+// src/webhook-router.ts
+var WebhookRouter = class {
+  constructor() {
+    /** pattern (composite key / entity wildcard / '*') → registered handlers. */
+    this.handlers = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Register a handler for an event pattern.
+   *
+   * @param pattern - `"{entity_type}.{event_type}"` (e.g. `opportunity.created`),
+   *   an entity wildcard `"{entity_type}.*"` (e.g. `opportunity.*`), or the
+   *   global wildcard `"*"`. Matching is exact-string against the derived key;
+   *   see the class docs for the dotted-`event_type` shape.
+   * @param handler - Invoked with the full {@link WebhookDelivery} on a match.
+   * @returns `this`, for chaining.
+   */
+  on(pattern, handler) {
+    const existing = this.handlers.get(pattern);
+    if (existing) {
+      existing.push(handler);
+    } else {
+      this.handlers.set(pattern, [handler]);
+    }
+    return this;
+  }
+  /**
+   * Verify, parse, and dispatch a webhook delivery.
+   *
+   * The signature is verified first: on failure this throws
+   * {@link WebhookVerificationError} and dispatches nothing. On success it
+   * dispatches to every matching handler — specific key, then entity wildcard,
+   * then global — awaiting async handlers before resolving.
+   *
+   * @param input - The raw `{ body, signature, secret }`.
+   * @returns The parsed {@link WebhookDelivery}.
+   * @throws WebhookVerificationError if the signature is invalid.
+   */
+  async process(input) {
+    const delivery = parseWebhookEvent(input.body, input.signature, input.secret);
+    const { entity_type, event_type } = delivery.event;
+    const patterns = [`${entity_type}.${event_type}`, `${entity_type}.*`, "*"];
+    for (const pattern of patterns) {
+      const matched = this.handlers.get(pattern);
+      if (!matched) continue;
+      for (const handler of matched) {
+        await handler(delivery);
+      }
+    }
+    return delivery;
+  }
+};
+
 // src/client.ts
-var BlueprintClient = class {
+var PlanesClient = class {
   constructor(config) {
-    if (!config.accessToken && !config.apiKey) {
-      throw new Error("BlueprintClient requires either accessToken or apiKey");
+    const hasOAuthCreds = Boolean(config.clientId) || Boolean(config.clientSecret);
+    const modes = [
+      config.accessToken ? "accessToken" : null,
+      config.apiKey ? "apiKey" : null,
+      hasOAuthCreds ? "clientId+clientSecret" : null
+    ].filter((m) => m !== null);
+    if (modes.length === 0) {
+      throw new Error(
+        "PlanesClient requires one auth mode: accessToken, apiKey, or clientId + clientSecret"
+      );
+    }
+    if (modes.length > 1) {
+      throw new Error(
+        `PlanesClient requires exactly one auth mode, not multiple (got: ${modes.join(", ")})`
+      );
     }
-    if (config.accessToken && config.apiKey) {
-      throw new Error("BlueprintClient requires either accessToken or apiKey, not both");
+    if (hasOAuthCreds && (!config.clientId || !config.clientSecret)) {
+      throw new Error("PlanesClient OAuth mode requires both clientId and clientSecret");
     }
     this.http = new HttpClient(config);
   }
@@ -358,17 +731,134 @@ var BlueprintClient = class {
     }
     return this._inventory;
   }
+  get contacts() {
+    if (!this._contacts) {
+      this._contacts = new ContactResource(this.http);
+    }
+    return this._contacts;
+  }
+  get activities() {
+    if (!this._activities) {
+      this._activities = new ActivityResource(this.http);
+    }
+    return this._activities;
+  }
+  get tags() {
+    if (!this._tags) {
+      this._tags = new TagResource(this.http);
+    }
+    return this._tags;
+  }
+  /**
+   * Ergonomic webhook event router — `client.webhooks.on(pattern, handler)`
+   * plus `client.webhooks.process({ body, signature, secret })`. Auth-independent
+   * (the signing secret is supplied per `.process()` call), so it is created
+   * lazily without the HTTP client. See {@link WebhookRouter}.
+   */
+  get webhooks() {
+    if (!this._webhooks) {
+      this._webhooks = new WebhookRouter();
+    }
+    return this._webhooks;
+  }
 };
 
 // src/agent.ts
 import * as http from "http";
-var Blueprint = {
+function createActionServer(handlerMap, options) {
+  const port = options?.port ?? 3e3;
+  const basePath = options?.path ?? "/actions";
+  const onError = options?.onError;
+  const server = http.createServer(async (req, res) => {
+    if (req.method !== "POST" || req.url !== basePath) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Not found" }));
+      return;
+    }
+    try {
+      const body = await readBody(req);
+      let envelope;
+      try {
+        envelope = JSON.parse(body);
+      } catch {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Malformed request body" }));
+        return;
+      }
+      const wire = envelope?.action_context;
+      const actionType = wire?.action_type;
+      if (!wire || !actionType) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({ error: "Missing action_context.action_type in request body" })
+        );
+        return;
+      }
+      const handler = handlerMap.get(actionType);
+      if (!handler) {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            error: `No handler registered for action type: ${actionType}`
+          })
+        );
+        return;
+      }
+      const requestIdHeader = req.headers["x-planes-request-id"];
+      const requestId = Array.isArray(requestIdHeader) ? requestIdHeader[0] : requestIdHeader;
+      const context = {
+        action_id: wire.action_id,
+        action_type: actionType,
+        entity_type: wire.entity_type,
+        entity_id: wire.entity_id,
+        tenant_id: wire.tenant_id,
+        data: wire.data ?? {},
+        stage: wire.stage ?? null,
+        metadata: wire.metadata,
+        callback_token: envelope.callback_token,
+        callback_base_url: envelope.callback_base_url,
+        // Only set request_id when the header was present (exactOptionalPropertyTypes).
+        ...requestId !== void 0 ? { request_id: requestId } : {}
+      };
+      let result;
+      try {
+        result = await handler.execute(context);
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : "Unknown handler error";
+        if (onError && err instanceof Error) {
+          onError(err);
+        }
+        result = {
+          status: "failed",
+          error: errorMessage,
+          retryable: false
+        };
+      }
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(result));
+    } catch (err) {
+      if (onError && err instanceof Error) {
+        onError(err);
+      }
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Internal server error" }));
+    }
+  });
+  server.listen(port);
+  const shutdown = () => {
+    server.close();
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+  return server;
+}
+var Planes = {
   /**
    * Register action handlers and start an HTTP server to receive action requests.
    *
    * @example
    * ```ts
-   * Blueprint.register([
+   * Planes.register([
    *   {
    *     type: 'send_email',
    *     async execute(ctx) {
@@ -380,77 +870,45 @@ var Blueprint = {
    * ```
    */
   register(handlers, options) {
-    const port = options?.port ?? 3e3;
-    const basePath = options?.path ?? "/actions";
-    const onError = options?.onError;
     const handlerMap = /* @__PURE__ */ new Map();
     for (const handler of handlers) {
       handlerMap.set(handler.type, handler);
     }
-    const server = http.createServer(async (req, res) => {
-      if (req.method !== "POST" || req.url !== basePath) {
-        res.writeHead(404, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Not found" }));
-        return;
-      }
-      try {
-        const body = await readBody(req);
-        let context;
-        try {
-          context = JSON.parse(body);
-        } catch {
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: "Malformed request body" }));
-          return;
-        }
-        if (!context.action?.type) {
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: "Missing action.type in request body" }));
-          return;
-        }
-        const handler = handlerMap.get(context.action.type);
-        if (!handler) {
-          res.writeHead(404, { "Content-Type": "application/json" });
-          res.end(
-            JSON.stringify({
-              error: `No handler registered for action type: ${context.action.type}`
-            })
-          );
-          return;
-        }
-        let result;
-        try {
-          result = await handler.execute(context);
-        } catch (err) {
-          const errorMessage = err instanceof Error ? err.message : "Unknown handler error";
-          if (onError && err instanceof Error) {
-            onError(err);
-          }
-          result = {
-            status: "failed",
-            error: errorMessage,
-            retryable: false
-          };
-        }
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify(result));
-      } catch (err) {
-        if (onError && err instanceof Error) {
-          onError(err);
-        }
-        res.writeHead(500, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Internal server error" }));
-      }
-    });
-    server.listen(port);
-    const shutdown = () => {
-      server.close();
-    };
-    process.on("SIGTERM", shutdown);
-    process.on("SIGINT", shutdown);
-    return server;
+    return createActionServer(handlerMap, options);
   }
 };
+var AgentApp = class {
+  constructor() {
+    this.handlers = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Register a handler for an action type. Accepts a bare `execute` function
+   * (the caller does not build the `{ type, execute }` object).
+   *
+   * @param type - The action type this handler responds to.
+   * @param execute - The handler function invoked with the {@link ActionContext}.
+   * @returns `this`, for chaining.
+   */
+  registerAction(type, execute) {
+    this.handlers.set(type, { type, execute });
+    return this;
+  }
+  /**
+   * Start an HTTP server that dispatches incoming action requests to the
+   * registered handlers. Delegates to the same server factory as
+   * {@link Planes.register}.
+   *
+   * The handler set is snapshotted at call time, so registering further actions
+   * after `listen()` does not mutate the running server (parity with
+   * `Planes.register`, which snapshots its array).
+   */
+  listen(options) {
+    return createActionServer(new Map(this.handlers), options);
+  }
+};
+function createAgentApp() {
+  return new AgentApp();
+}
 function readBody(req) {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -459,120 +917,42 @@ function readBody(req) {
     req.on("error", reject);
   });
 }
-
-// src/webhooks.ts
-import { createHmac, timingSafeEqual } from "crypto";
-function verifyWebhookSignature(payload, signature, secret) {
-  if (!signature || !secret || !payload) {
-    return false;
-  }
-  const prefix = "sha256=";
-  if (!signature.startsWith(prefix)) {
-    return false;
-  }
-  const receivedHex = signature.slice(prefix.length);
-  if (!receivedHex) {
-    return false;
-  }
-  const expectedHmac = createHmac("sha256", secret).update(payload).digest("hex");
-  const receivedBuf = Buffer.from(receivedHex, "hex");
-  const expectedBuf = Buffer.from(expectedHmac, "hex");
-  if (receivedBuf.length !== expectedBuf.length) {
-    return false;
-  }
-  return timingSafeEqual(receivedBuf, expectedBuf);
-}
-function parseWebhookEvent(body, signature, secret) {
-  if (!verifyWebhookSignature(body, signature, secret)) {
-    throw new WebhookVerificationError();
-  }
-  return JSON.parse(body);
-}
-
-// src/oauth.ts
-import { randomBytes } from "crypto";
-function buildAuthorizeUrl(options) {
-  const state = options.state ?? randomBytes(16).toString("hex");
-  const baseUrl = options.baseUrl.replace(/\/+$/, "");
-  const url = new URL(`${baseUrl}/oauth/authorize`);
-  url.searchParams.set("client_id", options.clientId);
-  url.searchParams.set("redirect_uri", options.redirectUri);
-  url.searchParams.set("scope", options.scopes.join(" "));
-  url.searchParams.set("response_type", "code");
-  url.searchParams.set("state", state);
-  return url.toString();
-}
-async function exchangeCode(options) {
-  const baseUrl = options.baseUrl.replace(/\/+$/, "");
-  const url = `${baseUrl}/oauth/token`;
-  const body = new URLSearchParams({
-    grant_type: "authorization_code",
-    client_id: options.clientId,
-    client_secret: options.clientSecret,
-    code: options.code,
-    redirect_uri: options.redirectUri
-  });
-  const response = await fetch(url, {
-    method: "POST",
-    headers: { "Content-Type": "application/x-www-form-urlencoded" },
-    body: body.toString()
-  });
-  if (!response.ok) {
-    const errorBody = await response.json().catch(() => ({}));
-    const errorCode = errorBody["error"] ?? "unknown_error";
-    const errorDescription = errorBody["error_description"] ?? "Token exchange failed";
-    throw new OAuthError(errorCode, errorDescription);
-  }
-  return await response.json();
-}
-async function refreshAccessToken(options) {
-  const baseUrl = options.baseUrl.replace(/\/+$/, "");
-  const url = `${baseUrl}/oauth/token`;
-  const body = new URLSearchParams({
-    grant_type: "refresh_token",
-    client_id: options.clientId,
-    client_secret: options.clientSecret,
-    refresh_token: options.refreshToken
-  });
-  const response = await fetch(url, {
-    method: "POST",
-    headers: { "Content-Type": "application/x-www-form-urlencoded" },
-    body: body.toString()
-  });
-  if (!response.ok) {
-    const errorBody = await response.json().catch(() => ({}));
-    const errorCode = errorBody["error"] ?? "unknown_error";
-    const errorDescription = errorBody["error_description"] ?? "Token refresh failed";
-    throw new OAuthError(errorCode, errorDescription);
-  }
-  return await response.json();
-}
 export {
+  ActivityResource,
+  AgentApp,
   AuthenticationError,
   AuthorizationError,
   BaseResource,
-  Blueprint,
-  BlueprintClient,
-  BlueprintError,
   CalendarEventResource,
+  ContactChannelResource,
+  ContactResource,
   ContractResource,
   CustomerResource,
   DEFAULT_BASE_URL,
   DEFAULT_MAX_RETRIES,
   DEFAULT_TIMEOUT,
+  DEFAULT_TOKEN_REFRESH_SKEW_MS,
   EstimateResource,
   InventoryResource,
   InvoiceResource,
   JobResource,
+  MemoryTokenStorage,
   NotFoundError,
   OAuthError,
   OpportunityResource,
+  Planes,
+  PlanesClient,
+  PlanesError,
   PropertyResource,
   RateLimitError,
   ServerError,
+  TagResource,
   ValidationError,
+  WebhookRouter,
   WebhookVerificationError,
   buildAuthorizeUrl,
+  clientCredentialsGrant,
+  createAgentApp,
   exchangeCode,
   parseWebhookEvent,
   refreshAccessToken,