@planescrm/sdk 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,15 +1,67 @@
 import * as http from 'node:http';
 
 /**
- * Configuration for the BlueprintClient.
+ * Tokens managed by an OAuth-credential client, persisted via {@link TokenStorage}.
  */
-interface BlueprintConfig {
+interface StoredTokens {
+    /** Current OAuth access token. */
+    accessToken: string;
+    /** Refresh token used to obtain a new access token. */
+    refreshToken: string;
+    /** Access-token expiry as epoch milliseconds. */
+    expiresAt: number;
+}
+/**
+ * Pluggable persistence for OAuth-managed tokens. Implement this to back the
+ * client with your own store (encrypted disk, database, secrets manager, ...).
+ * The default is {@link MemoryTokenStorage}.
+ */
+interface TokenStorage {
+    /** Load the currently stored tokens, or `null` if none are stored. */
+    getTokens(): Promise<StoredTokens | null>;
+    /** Persist the given tokens (called after every refresh). */
+    setTokens(tokens: StoredTokens): Promise<void>;
+}
+/**
+ * Default in-memory {@link TokenStorage}. Tokens live only for the process
+ * lifetime — provide your own implementation to persist across restarts.
+ */
+declare class MemoryTokenStorage implements TokenStorage {
+    private tokens;
+    constructor(seed?: StoredTokens | null);
+    getTokens(): Promise<StoredTokens | null>;
+    setTokens(tokens: StoredTokens): Promise<void>;
+}
+/**
+ * Configuration for the PlanesClient.
+ *
+ * Exactly one authentication mode must be supplied:
+ * - `accessToken` — a pre-obtained OAuth access token (not auto-refreshed)
+ * - `apiKey` — a `pk_live_` API key
+ * - `clientId` + `clientSecret` — OAuth-managed: the client obtains/refreshes
+ *   access tokens automatically using `tokenStorage`
+ */
+interface PlanesConfig {
     /** API base URL (defaults to https://api.planescrm.com/api/v1) */
     baseUrl?: string;
-    /** OAuth access token (mutually exclusive with apiKey) */
+    /** OAuth access token (mutually exclusive with apiKey / clientId+clientSecret) */
     accessToken?: string;
-    /** API key (mutually exclusive with accessToken) */
+    /** API key (mutually exclusive with accessToken / clientId+clientSecret) */
     apiKey?: string;
+    /** OAuth client ID — combined with `clientSecret`, enables the OAuth-managed path */
+    clientId?: string;
+    /** OAuth client secret — combined with `clientId`, enables the OAuth-managed path */
+    clientSecret?: string;
+    /**
+     * Token store for the OAuth-managed path. Seed it with tokens obtained from
+     * an authorization-code exchange. Defaults to {@link MemoryTokenStorage}.
+     */
+    tokenStorage?: TokenStorage;
+    /**
+     * Refresh access tokens proactively when they are within this many
+     * milliseconds of expiry (OAuth-managed path only). Default 60000 (60s).
+     */
+    tokenRefreshSkewMs?: number;
     /** Request timeout in milliseconds (default 30000) */
     timeout?: number;
     /** Automatically retry on 429 rate limit responses (default true) */
@@ -20,6 +72,7 @@ interface BlueprintConfig {
 declare const DEFAULT_BASE_URL = "https://api.planescrm.com/api/v1";
 declare const DEFAULT_TIMEOUT = 30000;
 declare const DEFAULT_MAX_RETRIES = 3;
+declare const DEFAULT_TOKEN_REFRESH_SKEW_MS = 60000;
 
 interface HttpRequestOptions {
     method: string;
@@ -39,9 +92,25 @@ declare class HttpClient {
     private readonly timeout;
     private readonly retryOnRateLimit;
     private readonly maxRetries;
-    constructor(config: BlueprintConfig);
+    private readonly oauth;
+    /** Single-flight guard so concurrent requests share one refresh. */
+    private refreshInFlight;
+    constructor(config: PlanesConfig);
     request<T>(options: HttpRequestOptions): Promise<T>;
     getAuthHeaders(): Record<string, string>;
+    /**
+     * 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.
+     */
+    private resolveAuthHeaders;
+    /**
+     * 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.
+     */
+    private refreshTokens;
     private buildUrl;
     private parseRetryAfter;
     private mapError;
@@ -151,15 +220,397 @@ declare class InventoryResource extends BaseResource {
 }
 
 /**
- * BlueprintClient — typed API client for the Planes CRM platform.
+ * Wire shapes for the Contacts + Contact Channels API.
+ *
+ * Mirrors `createContactSchema`/`updateContactSchema` and
+ * `createContactChannelSchema`/`updateContactChannelSchema` in
+ * `packages/shared/src/validation/contact.ts`, plus the actual Drizzle-row
+ * response shapes returned by `ContactsService` / `ContactChannelsService`.
+ * Types are redefined here (not imported) so the published package carries no
+ * runtime or type dependency on `@blueprint/shared`. Internal-only columns
+ * (tenantId, deletedAt, createdBy, …) are intentionally omitted — see
+ * `CustomerDto` for the house style.
+ */
+type ContactSource = 'manual' | 'import' | 'convert_from_customer';
+interface ContactDto {
+    id: string;
+    firstName: string;
+    lastName: string | null;
+    notes: string | null;
+    customFields: Record<string, unknown> | null;
+    source: ContactSource | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateContactDto {
+    firstName: string;
+    lastName?: string | null;
+    notes?: string | null;
+    customFields?: Record<string, unknown> | null;
+    source?: ContactSource | null;
+}
+interface UpdateContactDto {
+    firstName?: string;
+    lastName?: string | null;
+    notes?: string | null;
+    customFields?: Record<string, unknown> | null;
+    source?: ContactSource | null;
+}
+type ContactChannelType = 'email' | 'phone' | 'url';
+type ContactChannelPhoneType = 'mobile' | 'landline' | 'voip' | 'unknown';
+interface ContactChannelDto {
+    id: string;
+    contactId: string;
+    channelType: ContactChannelType;
+    label: string | null;
+    value: string;
+    isPrimary: boolean;
+    phoneType: ContactChannelPhoneType | null;
+    smsCapable: boolean | null;
+    dnc: boolean | null;
+    marketingOptOut: boolean | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateContactChannelDto {
+    channelType: ContactChannelType;
+    label?: string | null;
+    value: string;
+    isPrimary?: boolean;
+    dnc?: boolean | null;
+    marketingOptOut?: boolean | null;
+}
+interface UpdateContactChannelDto {
+    label?: string | null;
+    value?: string;
+    isPrimary?: boolean;
+    dnc?: boolean | null;
+    marketingOptOut?: boolean | null;
+}
+/** A channel elsewhere in the tenant with the same normalized value. */
+interface ContactChannelDuplicateMatch {
+    contactId: string;
+    channelId: string;
+    value: string;
+}
+/**
+ * `POST /contacts/:id/channels` return shape — `ContactChannelsService.addChannel()`
+ * always returns this wrapper, never a flat channel. `duplicateOf` is the
+ * dedup signal (empty array when there's no match) — the point of this API
+ * for connectors doing identity resolution (e.g. Messenger).
+ */
+interface AddContactChannelResult {
+    channel: ContactChannelDto;
+    duplicateOf: ContactChannelDuplicateMatch[];
+}
+interface ContactMergeResult {
+    winnerId: string;
+    loserId: string;
+}
+
+/**
+ * `/contacts/:id/channels` — POST/PATCH/DELETE only. There is no list/get
+ * route: reads come embedded in the contact detail response (`GET
+ * /contacts/:id` returns `{ ...contact, channels, links, mergedInto }`), so
+ * this does NOT extend `BaseResource`.
+ */
+declare class ContactChannelResource {
+    private readonly http;
+    private readonly basePath;
+    constructor(http: HttpClient, contactId: string);
+    /** Returns `{ channel, duplicateOf }` — `duplicateOf` is the dedup signal. */
+    create(data: CreateContactChannelDto): Promise<AddContactChannelResult>;
+    update(channelId: string, data: UpdateContactChannelDto): Promise<ContactChannelDto>;
+    delete(channelId: string): Promise<void>;
+}
+declare class ContactResource extends BaseResource<ContactDto, CreateContactDto, UpdateContactDto> {
+    constructor(http: ConstructorParameters<typeof BaseResource>[0]);
+    merge(winnerId: string, loserId: string): Promise<ContactMergeResult>;
+    channels(contactId: string): ContactChannelResource;
+}
+
+/**
+ * Wire shapes for the generic activity/timeline API (E31-F1).
+ *
+ * Mirrors `recordActivitySchema` (write) and `ActivityRecord` (read) in
+ * `packages/shared/src/validation/activity.ts` — both snake_case on the wire.
+ * Types are redefined here (not imported) so the published package carries no
+ * runtime or type dependency on `@blueprint/shared`.
+ */
+interface CreateActivityDto {
+    entity_type: string;
+    entity_id?: string | null;
+    /** The contact a channel-targeted send was addressed to, if any. */
+    contact_id?: string | null;
+    source: string;
+    type: string;
+    occurred_at?: string;
+    actor?: string | null;
+    /** Required — a short human-readable description of the event. */
+    summary: string;
+    external_ref?: string | null;
+    match_key?: string | null;
+    payload?: Record<string, unknown>;
+    payload_version?: number;
+}
+interface ActivityDto {
+    id: string;
+    type: string;
+    source: string;
+    occurred_at: string;
+    actor: string | null;
+    summary: string;
+    entity_type: string;
+    entity_id: string | null;
+    contact_id: string | null;
+    payload: Record<string, unknown>;
+}
+
+declare class ActivityResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(data: CreateActivityDto): Promise<ActivityDto>;
+    list(params?: ListParams): Promise<PaginatedResponse<ActivityDto>>;
+    listForEntity(entityType: string, entityId: string, params?: ListParams): Promise<PaginatedResponse<ActivityDto>>;
+}
+
+/**
+ * Wire shapes for the Tags & entity-tagging API.
+ *
+ * Mirrors `createTagSchema`/`updateTagSchema`/`setEntityTagsSchema` in
+ * `packages/shared/src/validation/tags.ts`, plus `TagsService`'s actual
+ * response shapes — snake_case, per `toDto()`/`list()`. Types are redefined
+ * here (not imported) so the published package carries no runtime or type
+ * dependency on `@blueprint/shared`.
+ */
+interface TagDto {
+    id: string;
+    name: string;
+    color: string | null;
+    created_at: string;
+    updated_at: string;
+    /** Only present on `list()` — `create()`/`update()` omit it. */
+    usage_count?: number;
+}
+interface CreateTagDto {
+    name: string;
+    color?: string | null;
+}
+interface UpdateTagDto {
+    name?: string;
+    color?: string | null;
+}
+/**
+ * Declarative set-tags input. Provide `tag_ids` and/or `tag_names` — at least
+ * one must be present (the server rejects neither); an empty array clears
+ * that side of the set.
+ */
+interface SetEntityTagsDto {
+    tag_ids?: string[];
+    tag_names?: string[];
+}
+interface EntityTagDto {
+    id: string;
+    name: string;
+    color: string | null;
+}
+interface TagEntityDto {
+    entity_type: string;
+    entity_id: string;
+}
+interface TagEntitiesPage {
+    data: TagEntityDto[];
+    page: number;
+    limit: number;
+    total: number;
+}
+
+declare class TagResource extends BaseResource<TagDto, CreateTagDto, UpdateTagDto> {
+    constructor(http: ConstructorParameters<typeof BaseResource>[0]);
+    /** `TagsService.setEntityTags()` returns the final tag set wrapped in `{ tags }`. */
+    setEntityTags(entityType: string, entityId: string, data: SetEntityTagsDto): Promise<{
+        tags: TagDto[];
+    }>;
+    getEntityTags(entityType: string, entityId: string): Promise<EntityTagDto[]>;
+    getEntities(tagId: string, params?: Record<string, unknown>): Promise<TagEntitiesPage>;
+}
+
+/**
+ * The kinds of change a webhook event can describe.
+ *
+ * Mirrored (self-contained, NOT imported) from
+ * `packages/shared/src/types/entity-events.ts` — the SDK must not depend on
+ * `@blueprint/shared`. Keep this union byte-identical to that source of truth.
+ */
+type EntityEventType = 'created' | 'updated' | 'deleted' | 'status_changed' | 'entity.tagged' | 'entity.untagged' | 'list.member_added' | 'list.member_removed' | 'entity.assigned' | 'entity.unassigned' | 'team.member_added' | 'team.member_removed' | 'task.created' | 'task.updated' | 'task.completed' | 'task.cancelled' | 'comment.created';
+/**
+ * The entity kinds a webhook event can target.
+ *
+ * Mirrored (self-contained, NOT imported) from
+ * `packages/shared/src/types/entity-events.ts`. Keep byte-identical.
+ */
+type EntityType = 'customer' | 'opportunity' | 'job' | 'estimate' | 'contract' | 'property' | 'inventory_item' | 'agent_execution' | 'calendar_event' | 'invoice' | 'payment';
+/**
+ * A single entity-change event as emitted onto the Planes event bus and
+ * delivered inside a {@link WebhookDelivery}.
+ *
+ * Mirrored from `EntityEvent` in
+ * `packages/shared/src/types/entity-events.ts`.
+ */
+interface EntityEvent {
+    /** What happened (e.g. 'created', 'status_changed'). */
+    event_type: EntityEventType;
+    /** The kind of record this event is about. */
+    entity_type: EntityType;
+    /** The affected record's ID. */
+    entity_id: string;
+    /** Tenant ID that owns this event. */
+    tenant_id: string;
+    /** Per-field before/after values for the change. */
+    changes: Record<string, {
+        old: unknown;
+        new: unknown;
+    }>;
+    /** Full record snapshot at the time of the event. */
+    snapshot: Record<string, unknown>;
+    /** ISO 8601 timestamp of when the event occurred. */
+    timestamp: string;
+    /** Correlation ID linking related events/actions. */
+    correlation_id: string;
+}
+/**
+ * The webhook delivery envelope Planes POSTs to a subscriber's URL.
+ *
+ * This is the outermost body: a delivery ID, the schema `version`, the wrapped
+ * {@link EntityEvent}, and the subscription that matched. The entity body lives
+ * at `event.snapshot` — there is no top-level `data`.
+ */
+interface WebhookDelivery {
+    /** Delivery ID (the delivery-log row id). */
+    id: string;
+    /**
+     * Webhook payload schema version (from the `X-Planes-Webhook-Version`
+     * header / envelope, emitted API-side per E39-F1-S2). v1 requires no
+     * branching; surfaced here so consumers can switch on it in the future.
+     */
+    version: number;
+    /** The entity-change event that triggered this delivery. */
+    event: EntityEvent;
+    /** ID of the webhook subscription that matched and produced this delivery. */
+    subscription_id: string;
+}
+/**
+ * Verify an HMAC-SHA256 webhook signature using timing-safe comparison.
+ *
+ * The signature header format is: `sha256=<hex-digest>`
+ *
+ * @param payload - The raw request body (string or Buffer)
+ * @param signature - The X-Planes-Signature header value
+ * @param secret - The webhook signing secret
+ * @returns true if the signature is valid, false otherwise
+ */
+declare function verifyWebhookSignature(payload: string | Buffer, signature: string, secret: string): boolean;
+/**
+ * Parse and verify a webhook delivery payload.
+ *
+ * @param body - The raw request body as a string
+ * @param signature - The X-Planes-Signature header value
+ * @param secret - The webhook signing secret
+ * @returns The parsed and verified {@link WebhookDelivery} envelope
+ * @throws WebhookVerificationError if signature is invalid
+ */
+declare function parseWebhookEvent(body: string, signature: string, secret: string): WebhookDelivery;
+
+/**
+ * A handler invoked for a matching webhook delivery. May be sync or async;
+ * async handlers are awaited by {@link WebhookRouter.process}.
+ */
+type WebhookHandler = (delivery: WebhookDelivery) => void | Promise<void>;
+/** Input to {@link WebhookRouter.process} — the raw request pieces. */
+interface WebhookProcessInput {
+    /** The raw request body as a string (verbatim — not re-serialized JSON). */
+    body: string;
+    /** The `X-Planes-Signature` header value (`sha256=<hex>`). */
+    signature: string;
+    /** The webhook signing secret for this subscription. */
+    secret: string;
+}
+/**
+ * Ergonomic event router over the corrected {@link WebhookDelivery} envelope.
+ *
+ * The platform models an event as two fields — `event.entity_type` and
+ * `event.event_type` — which this router joins into a dotted composite key
+ * `` `${entity_type}.${event_type}` `` (e.g. `opportunity.created`). Handlers
+ * subscribe to that key, to an entity-scoped wildcard `` `${entity_type}.*` ``
+ * (e.g. `opportunity.*`), or to the global wildcard `*`.
+ *
+ * The router is a pure dispatcher: it verifies + parses the delivery, then
+ * fans it out to matching handlers. It holds no connection and no auth — the
+ * signing secret is supplied per {@link process} call — so the same client's
+ * `webhooks` router works across subscriptions. Wire it into your own HTTP
+ * handler.
  *
  * @example
  * ```ts
- * const client = new BlueprintClient({ accessToken: 'tok_...' });
+ * client.webhooks
+ *   .on('opportunity.created', (d) => console.log(d.event.snapshot))
+ *   .on('opportunity.*', (d) => audit(d))
+ *   .on('*', (d) => metrics.count(d.event.entity_type));
+ *
+ * // inside your POST handler:
+ * await client.webhooks.process({ body: rawBody, signature, secret });
+ * ```
+ *
+ * ### Dotted `event_type` composite keys
+ *
+ * Four event types are themselves dotted — `entity.tagged`, `entity.untagged`,
+ * `list.member_added`, `list.member_removed`. Joined with their entity these
+ * yield keys with more than one dot, e.g. `customer.entity.tagged`. This router
+ * matches on the literal `` `${entity_type}.${event_type}` `` string, so
+ * subscribe with the full key (`'customer.entity.tagged'`). The entity wildcard
+ * (`'customer.*'`) and global wildcard (`'*'`) still match these deliveries;
+ * only mid-segment wildcards like `'customer.entity.*'` are intentionally
+ * unsupported.
+ */
+declare class WebhookRouter {
+    /** pattern (composite key / entity wildcard / '*') → registered handlers. */
+    private readonly handlers;
+    /**
+     * 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: string, handler: WebhookHandler): 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.
+     */
+    process(input: WebhookProcessInput): Promise<WebhookDelivery>;
+}
+
+/**
+ * PlanesClient — typed API client for the Planes CRM platform.
+ *
+ * @example
+ * ```ts
+ * const client = new PlanesClient({ accessToken: 'tok_...' });
  * const opps = await client.opportunities.list({ page: 1, limit: 20 });
  * ```
  */
-declare class BlueprintClient {
+declare class PlanesClient {
     private readonly http;
     private _opportunities?;
     private _customers?;
@@ -170,7 +621,11 @@ declare class BlueprintClient {
     private _estimates?;
     private _invoices?;
     private _inventory?;
-    constructor(config: BlueprintConfig);
+    private _contacts?;
+    private _activities?;
+    private _tags?;
+    private _webhooks?;
+    constructor(config: PlanesConfig);
     get opportunities(): OpportunityResource;
     get customers(): CustomerResource;
     get properties(): PropertyResource;
@@ -180,12 +635,22 @@ declare class BlueprintClient {
     get estimates(): EstimateResource;
     get invoices(): InvoiceResource;
     get inventory(): InventoryResource;
+    get contacts(): ContactResource;
+    get activities(): ActivityResource;
+    get tags(): TagResource;
+    /**
+     * 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(): WebhookRouter;
 }
 
 /**
  * Base error class for all Planes SDK errors.
  */
-declare class BlueprintError extends Error {
+declare class PlanesError extends Error {
     readonly status: number;
     readonly code: string;
     constructor(message: string, status: number, code: string);
@@ -193,19 +658,19 @@ declare class BlueprintError extends Error {
 /**
  * Thrown when authentication fails (401).
  */
-declare class AuthenticationError extends BlueprintError {
+declare class AuthenticationError extends PlanesError {
     constructor(message?: string);
 }
 /**
  * Thrown when the user lacks permission (403).
  */
-declare class AuthorizationError extends BlueprintError {
+declare class AuthorizationError extends PlanesError {
     constructor(message?: string);
 }
 /**
  * Thrown when a resource is not found (404).
  */
-declare class NotFoundError extends BlueprintError {
+declare class NotFoundError extends PlanesError {
     constructor(message?: string);
 }
 /** Field-level validation error detail. */
@@ -217,33 +682,33 @@ interface FieldError {
 /**
  * Thrown for validation failures (400) with field-level error details.
  */
-declare class ValidationError extends BlueprintError {
+declare class ValidationError extends PlanesError {
     readonly fieldErrors: FieldError[];
     constructor(message?: string, fieldErrors?: FieldError[]);
 }
 /**
  * Thrown when rate limited (429). Includes retryAfter in seconds.
  */
-declare class RateLimitError extends BlueprintError {
+declare class RateLimitError extends PlanesError {
     readonly retryAfter: number;
     constructor(retryAfter?: number, message?: string);
 }
 /**
  * Thrown for server errors (500+).
  */
-declare class ServerError extends BlueprintError {
+declare class ServerError extends PlanesError {
     constructor(message?: string);
 }
 /**
  * Thrown when webhook signature verification fails.
  */
-declare class WebhookVerificationError extends BlueprintError {
+declare class WebhookVerificationError extends PlanesError {
     constructor(message?: string);
 }
 /**
  * Thrown for OAuth flow errors.
  */
-declare class OAuthError extends BlueprintError {
+declare class OAuthError extends PlanesError {
     readonly errorCode: string;
     constructor(errorCode: string, message?: string);
 }
@@ -251,54 +716,130 @@ declare class OAuthError extends BlueprintError {
 /**
  * ActionHandler, ActionContext, and ActionResult types for the SDK.
  *
- * These mirror the types in @blueprint/shared/types/agent-execution.ts
- * but are self-contained to avoid requiring @blueprint/shared as a dependency.
- * The SDK is a standalone package for external developers.
+ * These model the REAL over-the-wire contract that the Planes platform's
+ * external-agent dispatcher POSTs to a registered agent endpoint
+ * (`apps/api/src/modules/marketplace/handlers/external-agent.handler.ts`).
+ * They are self-contained — the SDK never imports `@blueprint/shared`, so
+ * external developers can depend on this package alone.
+ *
+ * ## Wire contract (source of truth: external-agent.handler.ts)
+ *
+ * The platform POSTs a FLATTENED, WRAPPED envelope — NOT the platform's internal
+ * nested `ActionContext`:
+ *
+ * ```json
+ * {
+ *   "action_context": {
+ *     "action_id":   "act-1",
+ *     "action_type": "enrich-opportunity",
+ *     "entity_type": "opportunity",
+ *     "entity_id":   "opp-1",
+ *     "tenant_id":   "tenant-1",
+ *     "data":        { "...": "entity snapshot" },
+ *     "stage":       { "id": "...", "name": "...", "rules": null, "agent_role": null, "agent_instructions": null } | null,
+ *     "metadata":    { "trigger": { ... }, "execution": { ... } }
+ *   },
+ *   "callback_token":    "jwt.callback.token",
+ *   "callback_base_url": "https://…/api/v1"
+ * }
+ * ```
+ *
+ * ### Field convention
+ * The SDK mirrors the wire's **snake_case** verbatim (no camelCase translation),
+ * so a parsed request body maps 1:1 onto {@link ActionContext}. The one shaping
+ * the SDK server performs is to LIFT `callback_token` / `callback_base_url` (and
+ * the `X-Planes-Request-Id` header as {@link ActionContext.request_id}) up onto
+ * the same object handed to the handler — so a handler receives one flat context.
+ *
+ * ### Result delivery
+ * The platform reads the handler's {@link ActionResult} from the **synchronous
+ * HTTP response body** (`await response.json()` in the handler, dispatching on
+ * `status`). There is currently no async callback endpoint — `callback_token` /
+ * `callback_base_url` are minted for the agent to call back INTO the Planes API,
+ * not for the platform to poll. Handlers therefore just `return` their result.
+ *
+ * ### Not on the wire (intentionally absent vs. the platform's internal type)
+ * `permissions`, `agent_installation_id`, and `action.config` are NOT sent to
+ * external agents, so they are not modeled here.
  */
 /** Trigger types for action execution. */
 type TriggerType = 'workflow_transition' | 'schedule' | 'event' | 'agent';
-/** Permission levels (1 = most restricted, 4 = most powerful). */
+/**
+ * Permission levels (1 = most restricted, 4 = most powerful).
+ *
+ * Not part of the external wire envelope (the platform does not send permission
+ * metadata to external agents); retained as a public type for callers that
+ * reason about permission levels elsewhere.
+ */
 type PermissionLevel = 1 | 2 | 3 | 4;
+/** How this action was triggered (wire: `action_context.metadata.trigger`). */
+interface ActionTrigger {
+    type: TriggerType;
+    source_id: string;
+    triggered_by: string;
+}
+/** Execution/correlation metadata (wire: `action_context.metadata.execution`). */
+interface ActionExecution {
+    id: string;
+    correlation_id: string;
+    attempt: number;
+    timeout_ms: number;
+}
+/** Trigger + execution metadata (wire: `action_context.metadata`). */
+interface ActionMetadata {
+    trigger: ActionTrigger;
+    execution: ActionExecution;
+}
+/**
+ * Destination stage metadata — present for `workflow_transition` triggers,
+ * `null` otherwise (wire: `action_context.stage`).
+ */
+interface ActionStage {
+    id: string;
+    name: string;
+    rules: string | null;
+    agent_role: string | null;
+    agent_instructions: string | null;
+}
 /**
  * ActionContext envelope — passed to handlers on each invocation.
+ *
+ * Shape matches the platform's flattened `action_context` (see file header),
+ * with `callback_token`, `callback_base_url`, and `request_id` lifted onto the
+ * same object by the SDK server for handler convenience.
  */
 interface ActionContext {
-    trigger: {
-        type: TriggerType;
-        source_id: string;
-        triggered_by: string;
-    };
-    entity: {
-        type: string;
-        id: string;
-        snapshot: Record<string, unknown>;
-    };
-    action: {
-        id: string;
-        type: string;
-        config: Record<string, unknown>;
-    };
-    tenant: {
-        id: string;
-        scope_paths?: string[];
-    };
-    /** Agent installation ID — set for agent-type actions. */
-    agent_installation_id?: string;
-    permissions: {
-        level: PermissionLevel;
-        allowed_actions: string[];
-        spending_limit?: number;
-        spending_limit_daily?: number;
-        requires_approval: string[];
-        max_actions_per_execution?: number;
-        max_execution_time_ms?: number;
-    };
-    execution: {
-        id: string;
-        correlation_id: string;
-        attempt: number;
-        timeout_ms: number;
-    };
+    /** Unique ID of the action being executed (wire: `action_context.action_id`). */
+    action_id: string;
+    /** The action type — the SDK routes to a handler by this value. */
+    action_type: string;
+    /** The entity type this action operates on, e.g. `'opportunity'`. */
+    entity_type: string;
+    /** The entity's ID. */
+    entity_id: string;
+    /** The tenant (company) ID this action runs for. */
+    tenant_id: string;
+    /** The entity snapshot captured at trigger time (wire: `action_context.data`). */
+    data: Record<string, unknown>;
+    /** Destination stage metadata for workflow transitions; `null` otherwise. */
+    stage: ActionStage | null;
+    /** Trigger + execution metadata. */
+    metadata: ActionMetadata;
+    /**
+     * Short-lived (5-min) JWT for calling back INTO the Planes API at
+     * {@link callback_base_url}. Lifted from the envelope's top-level `callback_token`.
+     */
+    callback_token: string;
+    /**
+     * Base URL (e.g. `https://…/api/v1`) for authenticated callbacks using
+     * {@link callback_token}. Lifted from the envelope's top-level `callback_base_url`.
+     */
+    callback_base_url: string;
+    /**
+     * Per-invocation correlation ID from the `X-Planes-Request-Id` request header,
+     * for logging/idempotency. `undefined` if the header was absent.
+     */
+    request_id?: string;
 }
 /** A follow-up action request (used with delegated status). */
 interface ActionRequest {
@@ -308,6 +849,10 @@ interface ActionRequest {
 }
 /**
  * ActionResult — the return value from a handler's execute() method.
+ *
+ * The platform reads this from the synchronous HTTP response body and dispatches
+ * on `status` (`completed` → `output`, `failed` → `error`/`retryable`,
+ * `needs_human` → `reason`/`context`, `delegated` → `follow_up_actions`).
  */
 type ActionResult = {
     status: 'completed';
@@ -332,14 +877,15 @@ interface ActionHandler {
     execute(ctx: ActionContext): Promise<ActionResult>;
 }
 /**
- * Generic typed version of ActionHandler for specific input/output shapes.
+ * Generic typed version of ActionHandler for a specific entity-data/output shape.
+ *
+ * `TData` narrows {@link ActionContext.data} (the entity snapshot) — the external
+ * wire carries no per-action `config`, so typed handler input is the entity data.
  */
-interface AgentHandler<TInput = Record<string, unknown>, TOutput = unknown> {
+interface AgentHandler<TData = Record<string, unknown>, TOutput = unknown> {
     readonly type: string;
     execute(ctx: ActionContext & {
-        action: {
-            config: TInput;
-        };
+        data: TData;
     }): Promise<{
         status: 'completed';
         output?: TOutput;
@@ -362,7 +908,7 @@ interface AgentHandler<TInput = Record<string, unknown>, TOutput = unknown> {
 type HandlerMap = Record<string, ActionHandler>;
 
 /**
- * Options for Blueprint.register().
+ * Options for Planes.register() and AgentApp.listen().
  */
 interface RegisterOptions {
     /** Port to listen on (default 3000). */
@@ -375,16 +921,16 @@ interface RegisterOptions {
     onError?: (error: Error) => void;
 }
 /**
- * Blueprint agent registration namespace.
+ * Planes agent registration namespace.
  * Provides a convenient way to register action handlers as an HTTP server.
  */
-declare const Blueprint: {
+declare const 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) {
@@ -397,48 +943,49 @@ declare const Blueprint: {
      */
     register(handlers: ActionHandler[], options?: RegisterOptions): http.Server;
 };
-
-/**
- * Typed webhook event payload from Planes.
- */
-interface WebhookEvent<T = unknown> {
-    /** Event ID (e.g. evt_abc123). */
-    id: string;
-    /** Event type (e.g. opportunity.created). */
-    type: string;
-    /** Tenant ID that owns this event. */
-    tenant_id: string;
-    /** ISO 8601 timestamp of when the event occurred. */
-    timestamp: string;
-    /** Entity snapshot at the time of the event. */
-    data: T;
-    /** Metadata about the event trigger. */
-    metadata: {
-        correlation_id: string;
-        triggered_by: 'workflow' | 'api' | 'user';
-    };
-}
 /**
- * Verify an HMAC-SHA256 webhook signature using timing-safe comparison.
+ * Builder-style agent app. Register action handlers incrementally by type,
+ * then start the server with {@link AgentApp.listen}.
  *
- * The signature header format is: `sha256=<hex-digest>`
+ * This is ergonomic sugar over {@link Planes.register} — both share the same
+ * underlying server/dispatch implementation ({@link createActionServer}).
  *
- * @param payload - The raw request body (string or Buffer)
- * @param signature - The X-Blueprint-Signature header value
- * @param secret - The webhook signing secret
- * @returns true if the signature is valid, false otherwise
+ * @example
+ * ```ts
+ * createAgentApp()
+ *   .registerAction('enrich-opportunity', async (ctx) => {
+ *     // ... enrichment logic
+ *     return { status: 'completed', output: { enriched: true } };
+ *   })
+ *   .listen({ port: 3000 });
+ * ```
  */
-declare function verifyWebhookSignature(payload: string | Buffer, signature: string, secret: string): boolean;
+declare class AgentApp {
+    private readonly handlers;
+    /**
+     * 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: string, execute: ActionHandler['execute']): 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?: RegisterOptions): http.Server;
+}
 /**
- * Parse and verify a webhook event payload.
- *
- * @param body - The raw request body as a string
- * @param signature - The X-Blueprint-Signature header value
- * @param secret - The webhook signing secret
- * @returns The parsed and typed webhook event
- * @throws WebhookVerificationError if signature is invalid
+ * Create a new {@link AgentApp} builder.
  */
-declare function parseWebhookEvent<T = unknown>(body: string, signature: string, secret: string): WebhookEvent<T>;
+declare function createAgentApp(): AgentApp;
 
 /**
  * Options for building an OAuth authorization URL.
@@ -593,4 +1140,4 @@ interface CustomersGeneratedResource {
     createCustomer(data: CreateCustomerDto): Promise<CustomerDto>;
 }
 
-export { type ActionContext, type ActionHandler, type ActionRequest, type ActionResult, type AgentHandler, AuthenticationError, AuthorizationError, type AuthorizeOptions, BaseResource, Blueprint, BlueprintClient, type BlueprintConfig, BlueprintError, CalendarEventResource, ContractResource, type CreateCustomerDto, type CreateOpportunityDto, type CustomerDto, CustomerResource, type CustomersGeneratedResource, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, EstimateResource, type ExchangeCodeOptions, type FieldError, type HandlerMap, InventoryResource, InvoiceResource, JobResource, type ListParams, NotFoundError, OAuthError, type OpportunitiesGeneratedResource, type OpportunityDto, OpportunityResource, type PaginatedCustomerResponse, type PaginatedOpportunityResponse, type PaginatedResponse, type PaginationMeta, type PermissionLevel, PropertyResource, RateLimitError, type RefreshOptions, type RegisterOptions, ServerError, type TokenResponse, type TriggerType, type UpdateOpportunityDto, ValidationError, type WebhookEvent, WebhookVerificationError, buildAuthorizeUrl, exchangeCode, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };
+export { type ActionContext, type ActionHandler, type ActionRequest, type ActionResult, type ActivityDto, ActivityResource, AgentApp, type AgentHandler, AuthenticationError, AuthorizationError, type AuthorizeOptions, BaseResource, CalendarEventResource, type ContactChannelDto, ContactChannelResource, type ContactDto, type ContactMergeResult, ContactResource, ContractResource, type CreateActivityDto, type CreateContactChannelDto, type CreateContactDto, type CreateCustomerDto, type CreateOpportunityDto, type CreateTagDto, type CustomerDto, CustomerResource, type CustomersGeneratedResource, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, DEFAULT_TOKEN_REFRESH_SKEW_MS, type EntityEvent, type EntityEventType, type EntityTagDto, type EntityType, EstimateResource, type ExchangeCodeOptions, type FieldError, type HandlerMap, InventoryResource, InvoiceResource, JobResource, type ListParams, MemoryTokenStorage, NotFoundError, OAuthError, type OpportunitiesGeneratedResource, type OpportunityDto, OpportunityResource, type PaginatedCustomerResponse, type PaginatedOpportunityResponse, type PaginatedResponse, type PaginationMeta, type PermissionLevel, Planes, PlanesClient, type PlanesConfig, PlanesError, PropertyResource, RateLimitError, type RefreshOptions, type RegisterOptions, ServerError, type SetEntityTagsDto, type StoredTokens, type TagDto, type TagEntityDto, TagResource, type TokenResponse, type TokenStorage, type TriggerType, type UpdateContactChannelDto, type UpdateContactDto, type UpdateOpportunityDto, type UpdateTagDto, ValidationError, type WebhookDelivery, type WebhookHandler, type WebhookProcessInput, WebhookRouter, WebhookVerificationError, buildAuthorizeUrl, createAgentApp, exchangeCode, parseWebhookEvent, refreshAccessToken, verifyWebhookSignature };