@pgns/core 0.1.1

package/dist/events.js

@@ -0,0 +1,63 @@
+const DEFAULT_RETRY_DELAY = 3000;
+/**
+ * Connect to the Pgns SSE event stream using `fetch` + `ReadableStream`.
+ *
+ * Automatically reconnects on failure with a 3-second delay. Cancel the
+ * connection by aborting the signal passed in `opts`.
+ *
+ * @example
+ * ```ts
+ * const controller = new AbortController();
+ * createEventSource("https://api.pgns.io", {
+ *   token: "eyJhbG...",
+ *   signal: controller.signal,
+ *   onEvent(data) { console.log(data); },
+ * });
+ * // later: controller.abort();
+ * ```
+ */
+export async function createEventSource(baseUrl, opts) {
+    const url = opts.roostId
+        ? `${baseUrl}/v1/events?roost_id=${encodeURIComponent(opts.roostId)}`
+        : `${baseUrl}/v1/events`;
+    while (!opts.signal?.aborted) {
+        try {
+            const res = await fetch(url, {
+                headers: {
+                    ...(opts.token ? { Authorization: `Bearer ${opts.token}` } : {}),
+                    Accept: 'text/event-stream',
+                },
+                signal: opts.signal,
+            });
+            if (!res.ok || !res.body) {
+                throw new Error(`SSE connect failed: ${res.status}`);
+            }
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = '';
+            while (!opts.signal?.aborted) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    if (line.startsWith('data:')) {
+                        opts.onEvent(line.slice(5).trim());
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (opts.signal?.aborted)
+                break;
+            if (err instanceof DOMException && err.name === 'AbortError')
+                break;
+            opts.onError?.(err instanceof Error ? err : new Error(String(err)));
+        }
+        if (opts.signal?.aborted)
+            break;
+        await new Promise((r) => setTimeout(r, DEFAULT_RETRY_DELAY));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { PigeonsClient } from './client.js';
+export type { PigeonsClientConfig } from './client.js';
+export { PigeonsError } from './errors.js';
+export { createEventSource } from './events.js';
+export type { EventSourceOptions } from './events.js';
+export { ApiErrorSchema, ApiKeyCreatedResponseSchema, ApiKeyResponseSchema, AuthTokensSchema, CreateApiKeyRequestSchema, CreateDestinationSchema, CreateRoostSchema, DeliveryAttemptSchema, DeliveryStatusSchema, DestinationSchema, DestinationTypeSchema, LoginRequestSchema, MagicLinkRequestSchema, MagicLinkVerifyRequestSchema, PaginatedDeliveryAttemptsSchema, PaginatedPigeonsSchema, PaginatedResponseSchema, PigeonSchema, ReplayResponseSchema, RoostSchema, SignupRequestSchema, UpdateApiKeyRequestSchema, UpdateRoostSchema, } from './types.js';
+export type { ApiError, ApiKeyCreatedResponse, ApiKeyResponse, AuthTokens, CreateApiKeyRequest, CreateDestination, CreateRoost, DeliveryAttempt, DeliveryStatus, Destination, DestinationType, LoginRequest, MagicLinkRequest, MagicLinkVerifyRequest, PaginatedDeliveryAttempts, PaginatedPigeons, Pigeon, ReplayResponse, Roost, SignupRequest, UpdateApiKeyRequest, UpdateRoost, } from './types.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { PigeonsClient } from './client.js';
+export { PigeonsError } from './errors.js';
+export { createEventSource } from './events.js';
+// -- Schemas (Zod) --
+export { ApiErrorSchema, ApiKeyCreatedResponseSchema, ApiKeyResponseSchema, AuthTokensSchema, CreateApiKeyRequestSchema, CreateDestinationSchema, CreateRoostSchema, DeliveryAttemptSchema, DeliveryStatusSchema, DestinationSchema, DestinationTypeSchema, LoginRequestSchema, MagicLinkRequestSchema, MagicLinkVerifyRequestSchema, PaginatedDeliveryAttemptsSchema, PaginatedPigeonsSchema, PaginatedResponseSchema, PigeonSchema, ReplayResponseSchema, RoostSchema, SignupRequestSchema, UpdateApiKeyRequestSchema, UpdateRoostSchema, } from './types.js';

package/dist/types.d.ts

@@ -0,0 +1,355 @@
+import { z } from 'zod';
+/** Supported destination types for webhook forwarding. */
+export declare const DestinationTypeSchema: z.ZodEnum<{
+    url: "url";
+    slack: "slack";
+    discord: "discord";
+    email: "email";
+}>;
+export type DestinationType = z.infer<typeof DestinationTypeSchema>;
+/** Lifecycle status of a delivery attempt. */
+export declare const DeliveryStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    delivering: "delivering";
+    delivered: "delivered";
+    failed: "failed";
+    retrying: "retrying";
+}>;
+export type DeliveryStatus = z.infer<typeof DeliveryStatusSchema>;
+/** Token pair returned by authentication endpoints. */
+export declare const AuthTokensSchema: z.ZodObject<{
+    access_token: z.ZodString;
+    token_type: z.ZodString;
+    expires_in: z.ZodNumber;
+}, z.core.$strip>;
+export type AuthTokens = z.infer<typeof AuthTokensSchema>;
+/** Body for `POST /v1/auth/signup`. */
+export declare const SignupRequestSchema: z.ZodObject<{
+    email: z.ZodString;
+    password: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    tos_accepted: z.ZodBoolean;
+}, z.core.$strip>;
+export type SignupRequest = z.infer<typeof SignupRequestSchema>;
+/** Body for `POST /v1/auth/login`. */
+export declare const LoginRequestSchema: z.ZodObject<{
+    email: z.ZodString;
+    password: z.ZodString;
+}, z.core.$strip>;
+export type LoginRequest = z.infer<typeof LoginRequestSchema>;
+/** Body for `POST /v1/auth/magic-link`. */
+export declare const MagicLinkRequestSchema: z.ZodObject<{
+    email: z.ZodString;
+}, z.core.$strip>;
+export type MagicLinkRequest = z.infer<typeof MagicLinkRequestSchema>;
+/** Body for `POST /v1/auth/magic-link/verify`. */
+export declare const MagicLinkVerifyRequestSchema: z.ZodObject<{
+    token: z.ZodString;
+}, z.core.$strip>;
+export type MagicLinkVerifyRequest = z.infer<typeof MagicLinkVerifyRequestSchema>;
+/** An authenticated user account. */
+export declare const UserSchema: z.ZodObject<{
+    id: z.ZodString;
+    email: z.ZodString;
+    name: z.ZodString;
+    plan: z.ZodString;
+    tos_accepted_at: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+export type User = z.infer<typeof UserSchema>;
+/** A roost — a webhook endpoint that captures incoming requests. */
+export declare const RoostSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    secret: z.ZodNullable<z.ZodString>;
+    is_active: z.ZodBoolean;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+export type Roost = z.infer<typeof RoostSchema>;
+/** A captured webhook request. */
+export declare const PigeonSchema: z.ZodObject<{
+    id: z.ZodString;
+    roost_id: z.ZodString;
+    source_ip: z.ZodString;
+    request_method: z.ZodString;
+    content_type: z.ZodString;
+    headers: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    body_json: z.ZodNullable<z.ZodUnknown>;
+    body_raw: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+    request_query: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    filtered: z.ZodBoolean;
+    replayed_from: z.ZodNullable<z.ZodString>;
+    delivery_status: z.ZodEnum<{
+        pending: "pending";
+        delivering: "delivering";
+        delivered: "delivered";
+        failed: "failed";
+        retrying: "retrying";
+    }>;
+    received_at: z.ZodString;
+}, z.core.$strip>;
+export type Pigeon = z.infer<typeof PigeonSchema>;
+/** A forwarding target attached to a roost. */
+export declare const DestinationSchema: z.ZodObject<{
+    id: z.ZodString;
+    roost_id: z.ZodString;
+    destination_type: z.ZodEnum<{
+        url: "url";
+        slack: "slack";
+        discord: "discord";
+        email: "email";
+    }>;
+    config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    filter_expression: z.ZodString;
+    template: z.ZodString;
+    retry_max: z.ZodNumber;
+    retry_delay_ms: z.ZodNumber;
+    retry_multiplier: z.ZodNumber;
+    is_paused: z.ZodBoolean;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+export type Destination = z.infer<typeof DestinationSchema>;
+/** A single attempt to deliver a pigeon to a destination. */
+export declare const DeliveryAttemptSchema: z.ZodObject<{
+    id: z.ZodString;
+    pigeon_id: z.ZodString;
+    destination_id: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        delivering: "delivering";
+        delivered: "delivered";
+        failed: "failed";
+        retrying: "retrying";
+    }>;
+    attempt_number: z.ZodNumber;
+    response_status: z.ZodNullable<z.ZodNumber>;
+    response_body: z.ZodNullable<z.ZodString>;
+    error_message: z.ZodNullable<z.ZodString>;
+    attempted_at: z.ZodString;
+    next_retry_at: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type DeliveryAttempt = z.infer<typeof DeliveryAttemptSchema>;
+/** An API key (without the full key value). */
+export declare const ApiKeyResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    key_prefix: z.ZodString;
+    name: z.ZodString;
+    last_used: z.ZodNullable<z.ZodString>;
+    revoked_at: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+export type ApiKeyResponse = z.infer<typeof ApiKeyResponseSchema>;
+/** Response from creating an API key — includes the full key (shown only once). */
+export declare const ApiKeyCreatedResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    key: z.ZodString;
+    key_prefix: z.ZodString;
+    name: z.ZodString;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+export type ApiKeyCreatedResponse = z.infer<typeof ApiKeyCreatedResponseSchema>;
+/** Body for `POST /v1/roosts`. */
+export declare const CreateRoostSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    secret: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CreateRoost = z.infer<typeof CreateRoostSchema>;
+/** Body for `PATCH /v1/roosts/:id`. */
+export declare const UpdateRoostSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    secret: z.ZodOptional<z.ZodString>;
+    is_active: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type UpdateRoost = z.infer<typeof UpdateRoostSchema>;
+/** Body for `POST /v1/roosts/:id/destinations`. */
+export declare const CreateDestinationSchema: z.ZodObject<{
+    destination_type: z.ZodEnum<{
+        url: "url";
+        slack: "slack";
+        discord: "discord";
+        email: "email";
+    }>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    filter_expression: z.ZodOptional<z.ZodString>;
+    template: z.ZodOptional<z.ZodString>;
+    retry_max: z.ZodOptional<z.ZodNumber>;
+    retry_delay_ms: z.ZodOptional<z.ZodNumber>;
+    retry_multiplier: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CreateDestination = z.infer<typeof CreateDestinationSchema>;
+/** Body for `PATCH /v1/me`. */
+export declare const UpdateProfileRequestSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type UpdateProfileRequest = z.infer<typeof UpdateProfileRequestSchema>;
+/** Body for `POST /v1/api-keys`. */
+export declare const CreateApiKeyRequestSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CreateApiKeyRequest = z.infer<typeof CreateApiKeyRequestSchema>;
+/** Body for `PATCH /v1/api-keys/:id`. */
+export declare const UpdateApiKeyRequestSchema: z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>;
+export type UpdateApiKeyRequest = z.infer<typeof UpdateApiKeyRequestSchema>;
+/** Response from `POST /v1/pigeons/:id/replay`. */
+export declare const ReplayResponseSchema: z.ZodObject<{
+    replayed: z.ZodBoolean;
+    pigeon_id: z.ZodString;
+    delivery_attempts: z.ZodNumber;
+}, z.core.$strip>;
+export type ReplayResponse = z.infer<typeof ReplayResponseSchema>;
+/** Aggregated stats for the dashboard overview. */
+export declare const DashboardStatsSchema: z.ZodObject<{
+    total_roosts: z.ZodNumber;
+    active_roosts: z.ZodNumber;
+    total_pigeons: z.ZodNumber;
+    pigeons_today: z.ZodNumber;
+    delivered: z.ZodNumber;
+    failed: z.ZodNumber;
+}, z.core.$strip>;
+export type DashboardStats = z.infer<typeof DashboardStatsSchema>;
+/** A reusable template for formatting webhook payloads. */
+export declare const TemplateSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    body: z.ZodString;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+export type Template = z.infer<typeof TemplateSchema>;
+/** Body for `POST /v1/templates`. */
+export declare const CreateTemplateSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CreateTemplate = z.infer<typeof CreateTemplateSchema>;
+/** Body for `PATCH /v1/templates/:id`. */
+export declare const UpdateTemplateSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type UpdateTemplate = z.infer<typeof UpdateTemplateSchema>;
+/** Body for `POST /v1/templates/preview`. */
+export declare const PreviewTemplateRequestSchema: z.ZodObject<{
+    body: z.ZodString;
+    pigeon_id: z.ZodString;
+}, z.core.$strip>;
+export type PreviewTemplateRequest = z.infer<typeof PreviewTemplateRequestSchema>;
+/** Response from `POST /v1/templates/preview`. */
+export declare const PreviewTemplateResponseSchema: z.ZodObject<{
+    rendered: z.ZodString;
+}, z.core.$strip>;
+export type PreviewTemplateResponse = z.infer<typeof PreviewTemplateResponseSchema>;
+/** Generic paginated response envelope. */
+export declare function PaginatedResponseSchema<T extends z.ZodTypeAny>(itemSchema: T): z.ZodObject<{
+    data: z.ZodArray<T>;
+    next_cursor: z.ZodNullable<z.ZodString>;
+    has_more: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const PaginatedPigeonsSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        roost_id: z.ZodString;
+        source_ip: z.ZodString;
+        request_method: z.ZodString;
+        content_type: z.ZodString;
+        headers: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        body_json: z.ZodNullable<z.ZodUnknown>;
+        body_raw: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+        request_query: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        filtered: z.ZodBoolean;
+        replayed_from: z.ZodNullable<z.ZodString>;
+        delivery_status: z.ZodEnum<{
+            pending: "pending";
+            delivering: "delivering";
+            delivered: "delivered";
+            failed: "failed";
+            retrying: "retrying";
+        }>;
+        received_at: z.ZodString;
+    }, z.core.$strip>>;
+    next_cursor: z.ZodNullable<z.ZodString>;
+    has_more: z.ZodBoolean;
+}, z.core.$strip>;
+export type PaginatedPigeons = z.infer<typeof PaginatedPigeonsSchema>;
+export declare const PaginatedDeliveryAttemptsSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        pigeon_id: z.ZodString;
+        destination_id: z.ZodString;
+        status: z.ZodEnum<{
+            pending: "pending";
+            delivering: "delivering";
+            delivered: "delivered";
+            failed: "failed";
+            retrying: "retrying";
+        }>;
+        attempt_number: z.ZodNumber;
+        response_status: z.ZodNullable<z.ZodNumber>;
+        response_body: z.ZodNullable<z.ZodString>;
+        error_message: z.ZodNullable<z.ZodString>;
+        attempted_at: z.ZodString;
+        next_retry_at: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    next_cursor: z.ZodNullable<z.ZodString>;
+    has_more: z.ZodBoolean;
+}, z.core.$strip>;
+export type PaginatedDeliveryAttempts = z.infer<typeof PaginatedDeliveryAttemptsSchema>;
+export declare const BillingLimitsSchema: z.ZodObject<{
+    pigeons_per_month: z.ZodNumber;
+    max_roosts: z.ZodNumber;
+    api_per_minute: z.ZodNumber;
+    inbound_per_second: z.ZodNumber;
+    email_per_month: z.ZodNumber;
+}, z.core.$strip>;
+export type BillingLimits = z.infer<typeof BillingLimitsSchema>;
+export declare const BillingStatusSchema: z.ZodObject<{
+    plan: z.ZodString;
+    subscription_status: z.ZodString;
+    billing_period_start: z.ZodNullable<z.ZodString>;
+    billing_period_end: z.ZodNullable<z.ZodString>;
+    usage_count: z.ZodNumber;
+    limits: z.ZodObject<{
+        pigeons_per_month: z.ZodNumber;
+        max_roosts: z.ZodNumber;
+        api_per_minute: z.ZodNumber;
+        inbound_per_second: z.ZodNumber;
+        email_per_month: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type BillingStatus = z.infer<typeof BillingStatusSchema>;
+export declare const CheckoutRequestSchema: z.ZodObject<{
+    price_id: z.ZodString;
+    success_url: z.ZodString;
+    cancel_url: z.ZodString;
+}, z.core.$strip>;
+export type CheckoutRequest = z.infer<typeof CheckoutRequestSchema>;
+export declare const CheckoutResponseSchema: z.ZodObject<{
+    checkout_url: z.ZodString;
+}, z.core.$strip>;
+export type CheckoutResponse = z.infer<typeof CheckoutResponseSchema>;
+export declare const PortalRequestSchema: z.ZodObject<{
+    return_url: z.ZodString;
+}, z.core.$strip>;
+export type PortalRequest = z.infer<typeof PortalRequestSchema>;
+export declare const PortalResponseSchema: z.ZodObject<{
+    portal_url: z.ZodString;
+}, z.core.$strip>;
+export type PortalResponse = z.infer<typeof PortalResponseSchema>;
+/** Error body returned by the API on non-2xx responses. */
+export declare const ApiErrorSchema: z.ZodObject<{
+    error: z.ZodString;
+    status: z.ZodNumber;
+}, z.core.$strip>;
+export type ApiError = z.infer<typeof ApiErrorSchema>;

package/dist/types.js

@@ -0,0 +1,246 @@
+import { z } from 'zod';
+/** Supported destination types for webhook forwarding. */
+export const DestinationTypeSchema = z.enum(['url', 'slack', 'discord', 'email']);
+/** Lifecycle status of a delivery attempt. */
+export const DeliveryStatusSchema = z.enum([
+    'pending',
+    'delivering',
+    'delivered',
+    'failed',
+    'retrying',
+]);
+/** Token pair returned by authentication endpoints. */
+export const AuthTokensSchema = z.object({
+    access_token: z.string(),
+    token_type: z.string(),
+    expires_in: z.number(),
+});
+/** Body for `POST /v1/auth/signup`. */
+export const SignupRequestSchema = z.object({
+    email: z.string(),
+    password: z.string(),
+    name: z.string().optional(),
+    tos_accepted: z.boolean(),
+});
+/** Body for `POST /v1/auth/login`. */
+export const LoginRequestSchema = z.object({
+    email: z.string(),
+    password: z.string(),
+});
+/** Body for `POST /v1/auth/magic-link`. */
+export const MagicLinkRequestSchema = z.object({
+    email: z.string(),
+});
+/** Body for `POST /v1/auth/magic-link/verify`. */
+export const MagicLinkVerifyRequestSchema = z.object({
+    token: z.string(),
+});
+/** An authenticated user account. */
+export const UserSchema = z.object({
+    id: z.string(),
+    email: z.string(),
+    name: z.string(),
+    plan: z.string(),
+    tos_accepted_at: z.string().nullable(),
+    created_at: z.string(),
+    updated_at: z.string(),
+});
+/** A roost — a webhook endpoint that captures incoming requests. */
+export const RoostSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string(),
+    secret: z.string().nullable(),
+    is_active: z.boolean(),
+    created_at: z.string(),
+    updated_at: z.string(),
+});
+/** A captured webhook request. */
+export const PigeonSchema = z.object({
+    id: z.string(),
+    roost_id: z.string(),
+    source_ip: z.string(),
+    request_method: z.string(),
+    content_type: z.string(),
+    headers: z.record(z.string(), z.unknown()),
+    body_json: z.unknown().nullable(),
+    body_raw: z.array(z.number()).nullable(),
+    request_query: z.record(z.string(), z.unknown()).nullable(),
+    filtered: z.boolean(),
+    replayed_from: z.string().nullable(),
+    delivery_status: DeliveryStatusSchema,
+    received_at: z.string(),
+});
+/** A forwarding target attached to a roost. */
+export const DestinationSchema = z.object({
+    id: z.string(),
+    roost_id: z.string(),
+    destination_type: DestinationTypeSchema,
+    config: z.record(z.string(), z.unknown()),
+    filter_expression: z.string(),
+    template: z.string(),
+    retry_max: z.number(),
+    retry_delay_ms: z.number(),
+    retry_multiplier: z.number(),
+    is_paused: z.boolean(),
+    created_at: z.string(),
+    updated_at: z.string(),
+});
+/** A single attempt to deliver a pigeon to a destination. */
+export const DeliveryAttemptSchema = z.object({
+    id: z.string(),
+    pigeon_id: z.string(),
+    destination_id: z.string(),
+    status: DeliveryStatusSchema,
+    attempt_number: z.number(),
+    response_status: z.number().nullable(),
+    response_body: z.string().nullable(),
+    error_message: z.string().nullable(),
+    attempted_at: z.string(),
+    next_retry_at: z.string().nullable(),
+});
+/** An API key (without the full key value). */
+export const ApiKeyResponseSchema = z.object({
+    id: z.string(),
+    key_prefix: z.string(),
+    name: z.string(),
+    last_used: z.string().nullable(),
+    revoked_at: z.string().nullable(),
+    created_at: z.string(),
+});
+/** Response from creating an API key — includes the full key (shown only once). */
+export const ApiKeyCreatedResponseSchema = z.object({
+    id: z.string(),
+    key: z.string(),
+    key_prefix: z.string(),
+    name: z.string(),
+    created_at: z.string(),
+});
+/** Body for `POST /v1/roosts`. */
+export const CreateRoostSchema = z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    secret: z.string().optional(),
+});
+/** Body for `PATCH /v1/roosts/:id`. */
+export const UpdateRoostSchema = z.object({
+    name: z.string().optional(),
+    description: z.string().optional(),
+    secret: z.string().optional(),
+    is_active: z.boolean().optional(),
+});
+/** Body for `POST /v1/roosts/:id/destinations`. */
+export const CreateDestinationSchema = z.object({
+    destination_type: DestinationTypeSchema,
+    config: z.record(z.string(), z.unknown()).optional(),
+    filter_expression: z.string().optional(),
+    template: z.string().optional(),
+    retry_max: z.number().optional(),
+    retry_delay_ms: z.number().optional(),
+    retry_multiplier: z.number().optional(),
+});
+/** Body for `PATCH /v1/me`. */
+export const UpdateProfileRequestSchema = z.object({
+    name: z.string().optional(),
+    email: z.string().optional(),
+});
+/** Body for `POST /v1/api-keys`. */
+export const CreateApiKeyRequestSchema = z.object({
+    name: z.string().optional(),
+});
+/** Body for `PATCH /v1/api-keys/:id`. */
+export const UpdateApiKeyRequestSchema = z.object({
+    name: z.string(),
+});
+/** Response from `POST /v1/pigeons/:id/replay`. */
+export const ReplayResponseSchema = z.object({
+    replayed: z.boolean(),
+    pigeon_id: z.string(),
+    delivery_attempts: z.number(),
+});
+/** Aggregated stats for the dashboard overview. */
+export const DashboardStatsSchema = z.object({
+    total_roosts: z.number(),
+    active_roosts: z.number(),
+    total_pigeons: z.number(),
+    pigeons_today: z.number(),
+    delivered: z.number(),
+    failed: z.number(),
+});
+/** A reusable template for formatting webhook payloads. */
+export const TemplateSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string(),
+    body: z.string(),
+    created_at: z.string(),
+    updated_at: z.string(),
+});
+/** Body for `POST /v1/templates`. */
+export const CreateTemplateSchema = z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    body: z.string().optional(),
+});
+/** Body for `PATCH /v1/templates/:id`. */
+export const UpdateTemplateSchema = z.object({
+    name: z.string().optional(),
+    description: z.string().optional(),
+    body: z.string().optional(),
+});
+/** Body for `POST /v1/templates/preview`. */
+export const PreviewTemplateRequestSchema = z.object({
+    body: z.string(),
+    pigeon_id: z.string(),
+});
+/** Response from `POST /v1/templates/preview`. */
+export const PreviewTemplateResponseSchema = z.object({
+    rendered: z.string(),
+});
+/** Generic paginated response envelope. */
+export function PaginatedResponseSchema(itemSchema) {
+    return z.object({
+        data: z.array(itemSchema),
+        next_cursor: z.string().nullable(),
+        has_more: z.boolean(),
+    });
+}
+export const PaginatedPigeonsSchema = PaginatedResponseSchema(PigeonSchema);
+export const PaginatedDeliveryAttemptsSchema = PaginatedResponseSchema(DeliveryAttemptSchema);
+// ---------------------------------------------------------------------------
+// Billing
+// ---------------------------------------------------------------------------
+export const BillingLimitsSchema = z.object({
+    pigeons_per_month: z.number(),
+    max_roosts: z.number(),
+    api_per_minute: z.number(),
+    inbound_per_second: z.number(),
+    email_per_month: z.number(),
+});
+export const BillingStatusSchema = z.object({
+    plan: z.string(),
+    subscription_status: z.string(),
+    billing_period_start: z.string().nullable(),
+    billing_period_end: z.string().nullable(),
+    usage_count: z.number(),
+    limits: BillingLimitsSchema,
+});
+export const CheckoutRequestSchema = z.object({
+    price_id: z.string(),
+    success_url: z.string(),
+    cancel_url: z.string(),
+});
+export const CheckoutResponseSchema = z.object({
+    checkout_url: z.string(),
+});
+export const PortalRequestSchema = z.object({
+    return_url: z.string(),
+});
+export const PortalResponseSchema = z.object({
+    portal_url: z.string(),
+});
+/** Error body returned by the API on non-2xx responses. */
+export const ApiErrorSchema = z.object({
+    error: z.string(),
+    status: z.number(),
+});