@planescrm/sdk 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,596 @@
+import * as http from 'node:http';
+
+/**
+ * Configuration for the BlueprintClient.
+ */
+interface BlueprintConfig {
+    /** API base URL (defaults to https://api.planescrm.com/api/v1) */
+    baseUrl?: string;
+    /** OAuth access token (mutually exclusive with apiKey) */
+    accessToken?: string;
+    /** API key (mutually exclusive with accessToken) */
+    apiKey?: string;
+    /** Request timeout in milliseconds (default 30000) */
+    timeout?: number;
+    /** Automatically retry on 429 rate limit responses (default true) */
+    retryOnRateLimit?: boolean;
+    /** Maximum number of retries for rate-limited requests (default 3) */
+    maxRetries?: number;
+}
+declare const DEFAULT_BASE_URL = "https://api.planescrm.com/api/v1";
+declare const DEFAULT_TIMEOUT = 30000;
+declare const DEFAULT_MAX_RETRIES = 3;
+
+interface HttpRequestOptions {
+    method: string;
+    path: string;
+    body?: unknown;
+    params?: Record<string, unknown>;
+    headers?: Record<string, string>;
+}
+/**
+ * Internal HTTP client wrapper using native fetch.
+ * Handles authentication, rate limit retries, and error mapping.
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly accessToken;
+    private readonly apiKey;
+    private readonly timeout;
+    private readonly retryOnRateLimit;
+    private readonly maxRetries;
+    constructor(config: BlueprintConfig);
+    request<T>(options: HttpRequestOptions): Promise<T>;
+    getAuthHeaders(): Record<string, string>;
+    private buildUrl;
+    private parseRetryAfter;
+    private mapError;
+    private sleep;
+}
+
+/**
+ * Paginated list response wrapper.
+ */
+interface PaginatedResponse<T> {
+    data: T[];
+    meta: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+}
+/**
+ * Common filter/pagination parameters for list endpoints.
+ */
+interface ListParams {
+    page?: number;
+    limit?: number;
+    sort?: string;
+    order?: 'asc' | 'desc';
+    search?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Abstract base resource with standard CRUD methods.
+ * Generic parameters:
+ * - TEntity: the entity response type
+ * - TCreate: the create request body type
+ * - TUpdate: the update request body type
+ */
+declare abstract class BaseResource<TEntity = Record<string, unknown>, TCreate = Record<string, unknown>, TUpdate = Record<string, unknown>> {
+    protected readonly http: HttpClient;
+    protected readonly basePath: string;
+    constructor(http: HttpClient, basePath: string);
+    /**
+     * List entities with optional filters and pagination.
+     */
+    list(params?: ListParams): Promise<PaginatedResponse<TEntity>>;
+    /**
+     * Get a single entity by ID.
+     */
+    get(id: string): Promise<TEntity>;
+    /**
+     * Create a new entity.
+     */
+    create(data: TCreate): Promise<TEntity>;
+    /**
+     * Update an existing entity.
+     */
+    update(id: string, data: TUpdate): Promise<TEntity>;
+    /**
+     * Delete an entity by ID.
+     */
+    delete(id: string): Promise<void>;
+}
+
+/** Opportunity resource — CRUD operations on /opportunities. */
+declare class OpportunityResource extends BaseResource {
+    constructor(http: ConstructorParameters<typeof BaseResource>[0]);
+}
+
+/** Customer resource — CRUD operations on /customers. */
+declare class CustomerResource extends BaseResource {
+    constructor(http: ConstructorParameters<typeof BaseResource>[0]);
+}
+
+/** Property resource — CRUD operations on /properties. */
+declare class PropertyResource extends BaseResource {
+    constructor(http: ConstructorParameters<typeof BaseResource>[0]);
+}
+
+/** Calendar event resource — CRUD operations on /calendar-events. */
+declare class CalendarEventResource extends BaseResource {
+    constructor(http: ConstructorParameters<typeof BaseResource>[0]);
+}
+
+/** Contract resource — CRUD operations on /contracts. */
+declare class ContractResource extends BaseResource {
+    constructor(http: ConstructorParameters<typeof BaseResource>[0]);
+}
+
+/** Job resource — CRUD operations on /jobs. */
+declare class JobResource extends BaseResource {
+    constructor(http: ConstructorParameters<typeof BaseResource>[0]);
+}
+
+/** Estimate resource — CRUD operations on /estimates. */
+declare class EstimateResource extends BaseResource {
+    constructor(http: ConstructorParameters<typeof BaseResource>[0]);
+}
+
+/** Invoice resource — CRUD operations on /invoices. */
+declare class InvoiceResource extends BaseResource {
+    constructor(http: ConstructorParameters<typeof BaseResource>[0]);
+}
+
+/** Inventory resource — CRUD operations on /inventory/items. */
+declare class InventoryResource extends BaseResource {
+    constructor(http: ConstructorParameters<typeof BaseResource>[0]);
+}
+
+/**
+ * BlueprintClient — typed API client for the Planes CRM platform.
+ *
+ * @example
+ * ```ts
+ * const client = new BlueprintClient({ accessToken: 'tok_...' });
+ * const opps = await client.opportunities.list({ page: 1, limit: 20 });
+ * ```
+ */
+declare class BlueprintClient {
+    private readonly http;
+    private _opportunities?;
+    private _customers?;
+    private _properties?;
+    private _calendarEvents?;
+    private _contracts?;
+    private _jobs?;
+    private _estimates?;
+    private _invoices?;
+    private _inventory?;
+    constructor(config: BlueprintConfig);
+    get opportunities(): OpportunityResource;
+    get customers(): CustomerResource;
+    get properties(): PropertyResource;
+    get calendarEvents(): CalendarEventResource;
+    get contracts(): ContractResource;
+    get jobs(): JobResource;
+    get estimates(): EstimateResource;
+    get invoices(): InvoiceResource;
+    get inventory(): InventoryResource;
+}
+
+/**
+ * Base error class for all Planes SDK errors.
+ */
+declare class BlueprintError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status: number, code: string);
+}
+/**
+ * Thrown when authentication fails (401).
+ */
+declare class AuthenticationError extends BlueprintError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the user lacks permission (403).
+ */
+declare class AuthorizationError extends BlueprintError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when a resource is not found (404).
+ */
+declare class NotFoundError extends BlueprintError {
+    constructor(message?: string);
+}
+/** Field-level validation error detail. */
+interface FieldError {
+    field: string;
+    message: string;
+    code?: string;
+}
+/**
+ * Thrown for validation failures (400) with field-level error details.
+ */
+declare class ValidationError extends BlueprintError {
+    readonly fieldErrors: FieldError[];
+    constructor(message?: string, fieldErrors?: FieldError[]);
+}
+/**
+ * Thrown when rate limited (429). Includes retryAfter in seconds.
+ */
+declare class RateLimitError extends BlueprintError {
+    readonly retryAfter: number;
+    constructor(retryAfter?: number, message?: string);
+}
+/**
+ * Thrown for server errors (500+).
+ */
+declare class ServerError extends BlueprintError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when webhook signature verification fails.
+ */
+declare class WebhookVerificationError extends BlueprintError {
+    constructor(message?: string);
+}
+/**
+ * Thrown for OAuth flow errors.
+ */
+declare class OAuthError extends BlueprintError {
+    readonly errorCode: string;
+    constructor(errorCode: string, message?: string);
+}
+
+/**
+ * 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.
+ */
+/** Trigger types for action execution. */
+type TriggerType = 'workflow_transition' | 'schedule' | 'event' | 'agent';
+/** Permission levels (1 = most restricted, 4 = most powerful). */
+type PermissionLevel = 1 | 2 | 3 | 4;
+/**
+ * ActionContext envelope — passed to handlers on each invocation.
+ */
+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;
+    };
+}
+/** A follow-up action request (used with delegated status). */
+interface ActionRequest {
+    action_type: string;
+    config: Record<string, unknown>;
+    priority?: number;
+}
+/**
+ * ActionResult — the return value from a handler's execute() method.
+ */
+type ActionResult = {
+    status: 'completed';
+    output?: unknown;
+} | {
+    status: 'failed';
+    error: string;
+    retryable: boolean;
+} | {
+    status: 'needs_human';
+    reason: string;
+    context: unknown;
+} | {
+    status: 'delegated';
+    follow_up_actions: ActionRequest[];
+};
+/**
+ * ActionHandler interface — the core unit of agent logic.
+ */
+interface ActionHandler {
+    readonly type: string;
+    execute(ctx: ActionContext): Promise<ActionResult>;
+}
+/**
+ * Generic typed version of ActionHandler for specific input/output shapes.
+ */
+interface AgentHandler<TInput = Record<string, unknown>, TOutput = unknown> {
+    readonly type: string;
+    execute(ctx: ActionContext & {
+        action: {
+            config: TInput;
+        };
+    }): Promise<{
+        status: 'completed';
+        output?: TOutput;
+    } | {
+        status: 'failed';
+        error: string;
+        retryable: boolean;
+    } | {
+        status: 'needs_human';
+        reason: string;
+        context: unknown;
+    } | {
+        status: 'delegated';
+        follow_up_actions: ActionRequest[];
+    }>;
+}
+/**
+ * Record of action type string to handler — for type-safe handler registration.
+ */
+type HandlerMap = Record<string, ActionHandler>;
+
+/**
+ * Options for Blueprint.register().
+ */
+interface RegisterOptions {
+    /** Port to listen on (default 3000). */
+    port?: number;
+    /** HTTP path to listen on (default '/actions'). */
+    path?: string;
+    /** Whether to verify incoming request signatures (default true). */
+    verifySignature?: boolean;
+    /** Error callback for unhandled errors. */
+    onError?: (error: Error) => void;
+}
+/**
+ * Blueprint agent registration namespace.
+ * Provides a convenient way to register action handlers as an HTTP server.
+ */
+declare const Blueprint: {
+    /**
+     * Register action handlers and start an HTTP server to receive action requests.
+     *
+     * @example
+     * ```ts
+     * Blueprint.register([
+     *   {
+     *     type: 'send_email',
+     *     async execute(ctx) {
+     *       // ... send email logic
+     *       return { status: 'completed', output: { sent: true } };
+     *     },
+     *   },
+     * ], { port: 3000 });
+     * ```
+     */
+    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.
+ *
+ * The signature header format is: `sha256=<hex-digest>`
+ *
+ * @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
+ */
+declare function verifyWebhookSignature(payload: string | Buffer, signature: string, secret: string): boolean;
+/**
+ * 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
+ */
+declare function parseWebhookEvent<T = unknown>(body: string, signature: string, secret: string): WebhookEvent<T>;
+
+/**
+ * Options for building an OAuth authorization URL.
+ */
+interface AuthorizeOptions {
+    /** Planes API base URL (e.g. https://api.planescrm.com/api/v1). */
+    baseUrl: string;
+    /** OAuth client ID. */
+    clientId: string;
+    /** Redirect URI after authorization. */
+    redirectUri: string;
+    /** Requested OAuth scopes. */
+    scopes: string[];
+    /** CSRF state parameter (auto-generated if not provided). */
+    state?: string;
+}
+/**
+ * Options for exchanging an authorization code for tokens.
+ */
+interface ExchangeCodeOptions {
+    /** Planes API base URL. */
+    baseUrl: string;
+    /** OAuth client ID. */
+    clientId: string;
+    /** OAuth client secret. */
+    clientSecret: string;
+    /** Authorization code from the callback. */
+    code: string;
+    /** Redirect URI (must match the one used in authorization). */
+    redirectUri: string;
+}
+/**
+ * Options for refreshing an access token.
+ */
+interface RefreshOptions {
+    /** Planes API base URL. */
+    baseUrl: string;
+    /** OAuth client ID. */
+    clientId: string;
+    /** OAuth client secret. */
+    clientSecret: string;
+    /** Refresh token. */
+    refreshToken: string;
+}
+/**
+ * OAuth token response.
+ */
+interface TokenResponse {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    token_type: string;
+    scope: string;
+}
+/**
+ * Build an OAuth authorization URL for the Planes platform.
+ *
+ * @param options - Authorization options
+ * @returns The full authorization URL to redirect the user to
+ */
+declare function buildAuthorizeUrl(options: AuthorizeOptions): string;
+/**
+ * Exchange an authorization code for access and refresh tokens.
+ *
+ * @param options - Exchange options
+ * @returns Token response with access_token, refresh_token, etc.
+ * @throws OAuthError on failure
+ */
+declare function exchangeCode(options: ExchangeCodeOptions): Promise<TokenResponse>;
+/**
+ * Refresh an access token using a refresh token.
+ *
+ * @param options - Refresh options
+ * @returns New token response
+ * @throws OAuthError on failure
+ */
+declare function refreshAccessToken(options: RefreshOptions): Promise<TokenResponse>;
+
+interface OpportunityDto {
+    id: string;
+    name: string;
+    status: string;
+    priority?: 'low' | 'medium' | 'high' | 'urgent';
+    customerId?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateOpportunityDto {
+    name: string;
+    priority?: 'low' | 'medium' | 'high' | 'urgent';
+    customerId?: string;
+}
+interface UpdateOpportunityDto {
+    name?: string;
+    priority?: 'low' | 'medium' | 'high' | 'urgent';
+    customerId?: string;
+}
+interface PaginatedOpportunityResponse {
+    data: Array<OpportunityDto>;
+    meta: PaginationMeta;
+}
+interface CustomerDto {
+    id: string;
+    firstName: string;
+    lastName: string;
+    email?: string;
+    phone?: string;
+    createdAt: string;
+}
+interface CreateCustomerDto {
+    firstName: string;
+    lastName: string;
+    email?: string;
+    phone?: string;
+}
+interface PaginatedCustomerResponse {
+    data: Array<CustomerDto>;
+    meta: PaginationMeta;
+}
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+}
+
+/** Generated resource methods for Opportunities */
+interface OpportunitiesGeneratedResource {
+    /** List opportunities with pagination */
+    listOpportunities(params?: {
+        page?: number;
+        limit?: number;
+        search?: string;
+    }): Promise<PaginatedOpportunityResponse>;
+    /** Create a new opportunity */
+    createOpportunity(data: CreateOpportunityDto): Promise<OpportunityDto>;
+    /** Get opportunity by ID */
+    getOpportunity(id: string): Promise<OpportunityDto>;
+    /** Update an opportunity */
+    updateOpportunity(id: string, data: UpdateOpportunityDto): Promise<OpportunityDto>;
+    /** Delete an opportunity */
+    deleteOpportunity(id: string): Promise<void>;
+}
+/** Generated resource methods for Customers */
+interface CustomersGeneratedResource {
+    /** List customers with pagination */
+    listCustomers(params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedCustomerResponse>;
+    /** Create a new customer */
+    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 };