brigent-sdk 0.1.0

package/README.md

@@ -0,0 +1,184 @@
+# @brigent/sdk
+
+TypeScript SDK for the **Brigent** Agent-Native Infrastructure Platform.
+
+AI agents call Brigent to deploy services. Brigent orchestrates compute, databases, cache, storage, and domains — agents get back a live URL.
+
+## Install
+
+```bash
+npm install @brigent/sdk
+```
+
+## Quick Start
+
+```typescript
+import { BrigentClient } from "@brigent/sdk";
+
+const client = new BrigentClient({
+  apiKey: "brg_your_api_key",
+  baseUrl: "https://brigent-production.up.railway.app",
+});
+
+// Deploy a Docker image
+const deploy = await client.deploy({
+  type: "api",
+  name: "my-service",
+  source: { method: "docker_image", image: "nginx:alpine" },
+  health_check_path: "/",
+  budget_cap_usdc: "5.00",
+});
+
+// Wait for it to go live
+const detail = await client.monitor.waitForLive(deploy.deployment_id);
+console.log(`Live at: ${detail.url}`);
+```
+
+## API Reference
+
+### Deployments
+
+```typescript
+// Deploy a new service
+client.deploy(request: DeployRequest): Promise<DeployResponse>
+
+// Get deployment status and URL
+client.getDeployment(id: string): Promise<DeploymentDetail>
+
+// List all deployments
+client.listDeployments(options?): Promise<PaginatedResponse<DeploymentListItem>>
+
+// Delete / terminate a deployment
+client.deleteDeployment(id: string): Promise<void>
+
+// Fetch container logs
+client.getLogs(id: string, options?): Promise<LogEntry[]>
+
+// Scale replicas / memory
+client.scale(id: string, config: ScaleConfig): Promise<void>
+
+// Update environment variables
+client.updateEnv(id: string, envVars: Record<string, string>): Promise<void>
+```
+
+### Lifecycle
+
+```typescript
+client.pause(id: string)
+client.resume(id: string)
+client.restart(id: string)
+client.cancel(id: string)
+```
+
+### Monitoring
+
+```typescript
+// Poll until deployment is live (throws on failure/timeout)
+client.monitor.waitForLive(deploymentId, {
+  timeoutMs: 300_000,    // default: 5 min
+  pollIntervalMs: 3_000, // default: 3s
+})
+
+// Stream real-time events via SSE
+for await (const event of client.streamEvents(deploymentId)) {
+  console.log(event.status, event.data);
+}
+```
+
+### Cost & Billing
+
+```typescript
+client.getCost(id: string): Promise<CostResponse>
+client.estimate(request: Partial<DeployRequest>): Promise<CostEstimate>
+client.getBillingSummary(options?): Promise<BillingSummary>
+client.getPricing(): Promise<PricingResponse>
+client.getTier(): Promise<TierResponse>
+```
+
+### API Keys
+
+```typescript
+client.createApiKey({ name, scopes, rate_limit_tier }): Promise<ApiKeyResponse>
+client.listApiKeys(): Promise<ApiKeyListItem[]>
+client.deleteApiKey(id: string): Promise<void>
+```
+
+### Webhooks
+
+```typescript
+client.createWebhook({ url, events, secret }): Promise<WebhookResponse>
+client.listWebhooks(): Promise<WebhookListItem[]>
+client.updateWebhook(id, updates): Promise<WebhookListItem>
+client.deleteWebhook(id: string): Promise<void>
+
+// Verify incoming webhook signatures
+import { verifyWebhookSignature } from "@brigent/sdk";
+const valid = verifyWebhookSignature(payload, signature, secret);
+```
+
+### Templates
+
+```typescript
+client.createTemplate(params): Promise<TemplateResponse>
+client.listTemplates(): Promise<TemplateResponse[]>
+client.getTemplate(id: string): Promise<TemplateResponse>
+client.deleteTemplate(id: string): Promise<void>
+client.deployFromTemplate(templateId, { name, ...overrides }): Promise<DeployResponse>
+```
+
+### Custom Domains
+
+```typescript
+client.assignCustomDomain(deploymentId, "app.example.com"): Promise<CustomDomainResponse>
+```
+
+### Health
+
+```typescript
+client.getHealth(): Promise<HealthResponse>
+client.getReadiness(): Promise<ReadinessResponse>
+```
+
+## Error Handling
+
+```typescript
+import { BrigentApiError } from "@brigent/sdk";
+
+try {
+  await client.deploy(request);
+} catch (err) {
+  if (err instanceof BrigentApiError) {
+    console.log(err.code);            // "INVALID_REQUEST"
+    console.log(err.suggestedAction); // "Check the request body..."
+    console.log(err.status);          // 400
+    console.log(err.requestId);       // "abc-123"
+  }
+}
+```
+
+## Configuration
+
+```typescript
+const client = new BrigentClient({
+  apiKey: "brg_...",              // Required
+  baseUrl: "https://...",         // Default: https://api.brigent.dev
+  timeout: 30_000,               // Request timeout in ms
+  maxRetries: 2,                 // Auto-retry on 429/5xx
+});
+```
+
+## Deployment Types
+
+| Type | Compute | Database | Cache | Storage | Domain | Health Check |
+|------|---------|----------|-------|---------|--------|-------------|
+| `api` | Yes | Optional | Optional | Optional | Yes | Yes |
+| `fullstack` | Yes | Optional | Optional | Optional | Yes | Yes |
+| `frontend` | Yes | No | No | No | Yes | Yes |
+| `worker` | Yes | Optional | Optional | Optional | No | No |
+| `cron` | Yes | Optional | No | No | No | No |
+| `static_site` | No | No | No | Required | Yes | No |
+| `database_only` | No | Required | Optional | No | No | No |
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,81 @@
+import { DeploymentMonitor } from "./monitor.js";
+import type { StreamEventsOptions } from "./events.js";
+import type { AnalyticsOverview, AuditLogEntry, AuditLogOptions, BillingSummary, BillingSummaryOptions, CustomDomainResponse, DeploymentEvent, DeploymentMetrics, PricingResponse, TierResponse, TemplateCreateParams, TemplateResponse, WebhookDeliveryItem, ApiKeyCreateParams, ApiKeyListItem, ApiKeyResponse, BrigentClientOptions, CostEstimate, CostResponse, DeploymentDetail, DeploymentListItem, DeployRequest, DeployResponse, HealthResponse, ReadinessResponse, LogEntry, PaginatedResponse, ScaleConfig, WebhookCreateParams, WebhookListItem, WebhookResponse, WebhookUpdateParams } from "./types.js";
+export interface ListDeploymentsOptions {
+    status?: string;
+    type?: string;
+    page?: number;
+    per_page?: number;
+    sort?: string;
+    order?: "asc" | "desc";
+}
+export interface GetLogsOptions {
+    since?: string;
+    limit?: number;
+}
+export declare class BrigentClient {
+    private readonly http;
+    readonly monitor: DeploymentMonitor;
+    constructor(options: BrigentClientOptions);
+    deploy(request: DeployRequest): Promise<DeployResponse>;
+    getDeployment(id: string): Promise<DeploymentDetail>;
+    listDeployments(options?: ListDeploymentsOptions): Promise<PaginatedResponse<DeploymentListItem>>;
+    deleteDeployment(id: string): Promise<void>;
+    getLogs(id: string, options?: GetLogsOptions): Promise<LogEntry[]>;
+    scale(id: string, config: ScaleConfig): Promise<void>;
+    updateEnv(id: string, envVars: Record<string, string>): Promise<void>;
+    getCost(id: string): Promise<CostResponse>;
+    estimate(request: Partial<DeployRequest>): Promise<CostEstimate>;
+    createApiKey(params: ApiKeyCreateParams): Promise<ApiKeyResponse>;
+    listApiKeys(): Promise<ApiKeyListItem[]>;
+    deleteApiKey(id: string): Promise<void>;
+    createWebhook(params: WebhookCreateParams): Promise<WebhookResponse>;
+    listWebhooks(): Promise<WebhookListItem[]>;
+    deleteWebhook(id: string): Promise<void>;
+    updateWebhook(id: string, updates: WebhookUpdateParams): Promise<WebhookListItem>;
+    getWebhookDeliveries(webhookId: string, options?: {
+        page?: number;
+        per_page?: number;
+    }): Promise<PaginatedResponse<WebhookDeliveryItem>>;
+    replayWebhookDelivery(webhookId: string, deliveryId: string): Promise<{
+        delivery_id: string;
+        status: string;
+    }>;
+    getHealth(): Promise<HealthResponse>;
+    getReadiness(): Promise<ReadinessResponse>;
+    getAnalyticsOverview(): Promise<AnalyticsOverview>;
+    getDeploymentMetrics(id: string): Promise<DeploymentMetrics>;
+    getAuditLog(options?: AuditLogOptions): Promise<PaginatedResponse<AuditLogEntry>>;
+    getBillingSummary(options?: BillingSummaryOptions): Promise<BillingSummary>;
+    getPricing(): Promise<PricingResponse>;
+    getTier(): Promise<TierResponse>;
+    createTemplate(params: TemplateCreateParams): Promise<TemplateResponse>;
+    listTemplates(): Promise<TemplateResponse[]>;
+    getTemplate(id: string): Promise<TemplateResponse>;
+    deleteTemplate(id: string): Promise<void>;
+    deployFromTemplate(templateId: string, overrides: {
+        name: string;
+    } & Partial<DeployRequest>): Promise<DeployResponse>;
+    pause(id: string): Promise<{
+        deployment_id: string;
+        status: string;
+    }>;
+    resume(id: string): Promise<{
+        deployment_id: string;
+        status: string;
+    }>;
+    restart(id: string): Promise<{
+        deployment_id: string;
+        status: string;
+    }>;
+    cancel(id: string): Promise<{
+        deployment_id: string;
+        status: string;
+    }>;
+    assignCustomDomain(deploymentId: string, domain: string): Promise<CustomDomainResponse>;
+    /**
+     * Stream real-time deployment status events via SSE.
+     * Returns an async generator yielding DeploymentEvent objects.
+     */
+    streamEvents(deploymentId: string, options?: StreamEventsOptions): AsyncGenerator<DeploymentEvent>;
+}

package/dist/client.js

@@ -0,0 +1,190 @@
+import { HttpClient } from "./http.js";
+import { DeploymentMonitor } from "./monitor.js";
+import { streamDeploymentEvents } from "./events.js";
+const DEFAULT_BASE_URL = "https://api.brigent.dev";
+const DEFAULT_TIMEOUT = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
+export class BrigentClient {
+    http;
+    monitor;
+    constructor(options) {
+        this.http = new HttpClient({
+            baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+            apiKey: options.apiKey,
+            timeout: options.timeout ?? DEFAULT_TIMEOUT,
+            maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+        });
+        this.monitor = new DeploymentMonitor(this.http);
+    }
+    // --- Deployments ---
+    async deploy(request) {
+        return this.http.post("/v1/deploy", request);
+    }
+    async getDeployment(id) {
+        return this.http.get(`/v1/deployments/${id}`);
+    }
+    async listDeployments(options) {
+        const params = new URLSearchParams();
+        if (options?.status)
+            params.set("status", options.status);
+        if (options?.type)
+            params.set("type", options.type);
+        if (options?.page)
+            params.set("page", String(options.page));
+        if (options?.per_page)
+            params.set("per_page", String(options.per_page));
+        if (options?.sort)
+            params.set("sort", options.sort);
+        if (options?.order)
+            params.set("order", options.order);
+        const qs = params.toString();
+        return this.http.get(`/v1/deployments${qs ? `?${qs}` : ""}`);
+    }
+    async deleteDeployment(id) {
+        await this.http.delete(`/v1/deployments/${id}`);
+    }
+    async getLogs(id, options) {
+        const params = new URLSearchParams();
+        if (options?.since)
+            params.set("since", options.since);
+        if (options?.limit)
+            params.set("limit", String(options.limit));
+        const qs = params.toString();
+        const response = await this.http.get(`/v1/deployments/${id}/logs${qs ? `?${qs}` : ""}`);
+        return response.logs;
+    }
+    async scale(id, config) {
+        await this.http.post(`/v1/deployments/${id}/scale`, config);
+    }
+    async updateEnv(id, envVars) {
+        await this.http.patch(`/v1/deployments/${id}`, { env_vars: envVars });
+    }
+    // --- Cost ---
+    async getCost(id) {
+        return this.http.get(`/v1/deployments/${id}/cost`);
+    }
+    async estimate(request) {
+        return this.http.post("/v1/estimate", request);
+    }
+    // --- API Keys ---
+    async createApiKey(params) {
+        return this.http.post("/v1/account/keys", params);
+    }
+    async listApiKeys() {
+        const response = await this.http.get("/v1/account/keys");
+        return response.keys;
+    }
+    async deleteApiKey(id) {
+        await this.http.delete(`/v1/account/keys/${id}`);
+    }
+    // --- Webhooks ---
+    async createWebhook(params) {
+        return this.http.post("/v1/webhooks", params);
+    }
+    async listWebhooks() {
+        const response = await this.http.get("/v1/webhooks");
+        return response.webhooks;
+    }
+    async deleteWebhook(id) {
+        await this.http.delete(`/v1/webhooks/${id}`);
+    }
+    async updateWebhook(id, updates) {
+        return this.http.patch(`/v1/webhooks/${id}`, updates);
+    }
+    async getWebhookDeliveries(webhookId, options) {
+        const params = new URLSearchParams();
+        if (options?.page)
+            params.set("page", String(options.page));
+        if (options?.per_page)
+            params.set("per_page", String(options.per_page));
+        const qs = params.toString();
+        return this.http.get(`/v1/webhooks/${webhookId}/deliveries${qs ? `?${qs}` : ""}`);
+    }
+    async replayWebhookDelivery(webhookId, deliveryId) {
+        return this.http.post(`/v1/webhooks/${webhookId}/deliveries/${deliveryId}/replay`, {});
+    }
+    // --- Health ---
+    async getHealth() {
+        return this.http.get("/v1/health");
+    }
+    async getReadiness() {
+        return this.http.get("/v1/health/ready");
+    }
+    // --- Analytics ---
+    async getAnalyticsOverview() {
+        return this.http.get("/v1/analytics/overview");
+    }
+    async getDeploymentMetrics(id) {
+        return this.http.get(`/v1/analytics/deployments/${id}/metrics`);
+    }
+    async getAuditLog(options) {
+        const params = new URLSearchParams();
+        if (options?.action)
+            params.set("action", options.action);
+        if (options?.since)
+            params.set("since", options.since);
+        if (options?.page)
+            params.set("page", String(options.page));
+        if (options?.per_page)
+            params.set("per_page", String(options.per_page));
+        const qs = params.toString();
+        return this.http.get(`/v1/account/audit${qs ? `?${qs}` : ""}`);
+    }
+    async getBillingSummary(options) {
+        const params = new URLSearchParams();
+        if (options?.since)
+            params.set("since", options.since);
+        if (options?.until)
+            params.set("until", options.until);
+        const qs = params.toString();
+        return this.http.get(`/v1/account/billing/summary${qs ? `?${qs}` : ""}`);
+    }
+    // --- Pricing ---
+    async getPricing() {
+        return this.http.get("/v1/pricing");
+    }
+    async getTier() {
+        return this.http.get("/v1/account/tier");
+    }
+    // --- Templates ---
+    async createTemplate(params) {
+        return this.http.post("/v1/templates", params);
+    }
+    async listTemplates() {
+        return this.http.get("/v1/templates");
+    }
+    async getTemplate(id) {
+        return this.http.get(`/v1/templates/${id}`);
+    }
+    async deleteTemplate(id) {
+        await this.http.delete(`/v1/templates/${id}`);
+    }
+    async deployFromTemplate(templateId, overrides) {
+        return this.http.post("/v1/deploy", { ...overrides, template_id: templateId });
+    }
+    // --- Lifecycle ---
+    async pause(id) {
+        return this.http.post(`/v1/deployments/${id}/pause`, {});
+    }
+    async resume(id) {
+        return this.http.post(`/v1/deployments/${id}/resume`, {});
+    }
+    async restart(id) {
+        return this.http.post(`/v1/deployments/${id}/restart`, {});
+    }
+    async cancel(id) {
+        return this.http.post(`/v1/deployments/${id}/cancel`, {});
+    }
+    // --- Custom Domains ---
+    async assignCustomDomain(deploymentId, domain) {
+        return this.http.post(`/v1/deployments/${deploymentId}/domains`, { domain });
+    }
+    // --- SSE Events ---
+    /**
+     * Stream real-time deployment status events via SSE.
+     * Returns an async generator yielding DeploymentEvent objects.
+     */
+    streamEvents(deploymentId, options) {
+        return streamDeploymentEvents(this.http.baseUrl, this.http.apiKey, deploymentId, options);
+    }
+}

package/dist/cost.d.ts

@@ -0,0 +1,13 @@
+import type { CostEstimate, DeploymentType } from "./types.js";
+export interface EstimateOptions {
+    type?: DeploymentType;
+    database?: boolean;
+    cache?: boolean;
+    storage?: boolean;
+    tierMultiplier?: number;
+}
+/**
+ * Client-side cost estimation that mirrors the server-side logic.
+ * Useful for building UIs that show cost previews before deploying.
+ */
+export declare function estimateCost(options?: EstimateOptions): CostEstimate;

package/dist/cost.js

@@ -0,0 +1,106 @@
+const PRICING = {
+    build: { unit: "per build", unitPrice: 0.10 },
+    compute: { unit: "per hour", unitPrice: 0.03 },
+    database: { unit: "per hour", unitPrice: 0.01 },
+    cache: { unit: "per hour", unitPrice: 0.005 },
+    storage: { unit: "per hour", unitPrice: 0.002 },
+    domain: { unit: "included", unitPrice: 0.00 },
+};
+const HOURS_PER_MONTH = 720;
+/**
+ * Client-side cost estimation that mirrors the server-side logic.
+ * Useful for building UIs that show cost previews before deploying.
+ */
+export function estimateCost(options = {}) {
+    const multiplier = options.tierMultiplier ?? 1.0;
+    const isStaticSite = options.type === "static_site";
+    const isDatabaseOnly = options.type === "database_only";
+    const breakdown = [];
+    // Build cost (skipped for static_site and database_only)
+    if (!isStaticSite && !isDatabaseOnly) {
+        const price = PRICING.build.unitPrice * multiplier;
+        breakdown.push({
+            resource: "build",
+            unit: PRICING.build.unit,
+            unit_price_usdc: formatPrice(price),
+            quantity: 1,
+            subtotal_usdc: formatPrice(price),
+        });
+    }
+    // Compute (skipped for static_site and database_only)
+    if (!isStaticSite && !isDatabaseOnly) {
+        const price = PRICING.compute.unitPrice * multiplier;
+        breakdown.push({
+            resource: "compute",
+            unit: PRICING.compute.unit,
+            unit_price_usdc: formatPrice(price),
+            quantity: 1,
+            subtotal_usdc: formatPrice(price),
+        });
+    }
+    // Database
+    if (options.database || isDatabaseOnly) {
+        const price = PRICING.database.unitPrice * multiplier;
+        breakdown.push({
+            resource: "database",
+            unit: PRICING.database.unit,
+            unit_price_usdc: formatPrice(price),
+            quantity: 1,
+            subtotal_usdc: formatPrice(price),
+        });
+    }
+    // Cache
+    if (options.cache) {
+        const price = PRICING.cache.unitPrice * multiplier;
+        breakdown.push({
+            resource: "cache",
+            unit: PRICING.cache.unit,
+            unit_price_usdc: formatPrice(price),
+            quantity: 1,
+            subtotal_usdc: formatPrice(price),
+        });
+    }
+    // Storage
+    if (options.storage || isStaticSite) {
+        const price = PRICING.storage.unitPrice * multiplier;
+        breakdown.push({
+            resource: "storage",
+            unit: PRICING.storage.unit,
+            unit_price_usdc: formatPrice(price),
+            quantity: 1,
+            subtotal_usdc: formatPrice(price),
+        });
+    }
+    // Domain (skipped for database_only)
+    if (!isDatabaseOnly) {
+        breakdown.push({
+            resource: "domain",
+            unit: PRICING.domain.unit,
+            unit_price_usdc: formatPrice(PRICING.domain.unitPrice * multiplier),
+            quantity: 1,
+            subtotal_usdc: formatPrice(PRICING.domain.unitPrice * multiplier),
+        });
+    }
+    // Calculate totals
+    const setupUsdc = breakdown
+        .filter((i) => i.resource === "build")
+        .reduce((sum, i) => sum + parseFloat(i.subtotal_usdc), 0);
+    const hourlyUsdc = breakdown
+        .filter((i) => i.resource !== "build" && i.resource !== "domain")
+        .reduce((sum, i) => sum + parseFloat(i.subtotal_usdc), 0);
+    return {
+        setup_usdc: setupUsdc.toFixed(2),
+        hourly_usdc: hourlyUsdc.toFixed(2),
+        monthly_estimate_usdc: (setupUsdc + hourlyUsdc * HOURS_PER_MONTH).toFixed(2),
+        breakdown,
+    };
+}
+function formatPrice(value) {
+    // For prices like 0.005, 0.002 — preserve significant decimals
+    if (value === 0)
+        return "0.00";
+    const str = value.toString();
+    const decimalPart = str.split(".")[1] ?? "";
+    const minDecimals = Math.max(2, decimalPart.length);
+    return value.toFixed(minDecimals);
+}

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+import type { BrigentErrorBody } from "./types.js";
+export declare class BrigentApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly suggestedAction: string;
+    readonly requestId: string;
+    readonly retryAfterSeconds?: number;
+    readonly details?: Record<string, unknown>;
+    constructor(status: number, body: BrigentErrorBody);
+}

package/dist/errors.js

@@ -0,0 +1,18 @@
+export class BrigentApiError extends Error {
+    status;
+    code;
+    suggestedAction;
+    requestId;
+    retryAfterSeconds;
+    details;
+    constructor(status, body) {
+        super(body.error.message);
+        this.name = "BrigentApiError";
+        this.status = status;
+        this.code = body.error.code;
+        this.suggestedAction = body.error.suggested_action;
+        this.requestId = body.request_id;
+        this.retryAfterSeconds = body.error.retry_after_seconds;
+        this.details = body.error.details;
+    }
+}

package/dist/events.d.ts

@@ -0,0 +1,29 @@
+export interface DeploymentEvent {
+    deployment_id: string;
+    status: string;
+    previous_status?: string;
+    timestamp: string;
+    failure_reason?: string;
+}
+export interface StreamEventsOptions {
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Maximum reconnect attempts (default: 5) */
+    maxReconnectAttempts?: number;
+    /** Base reconnect delay in ms (default: 1000, uses exponential backoff) */
+    reconnectDelayMs?: number;
+}
+/**
+ * Stream deployment events via SSE.
+ * Returns an async iterable that yields DeploymentEvent objects.
+ * Supports auto-reconnect with exponential backoff.
+ *
+ * Usage:
+ * ```typescript
+ * for await (const event of streamDeploymentEvents(baseUrl, apiKey, "dep_123")) {
+ *   console.log(event.status);
+ *   if (event.status === "live") break;
+ * }
+ * ```
+ */
+export declare function streamDeploymentEvents(baseUrl: string, apiKey: string, deploymentId: string, options?: StreamEventsOptions): AsyncGenerator<DeploymentEvent>;