@agentuity/core 1.0.34 → 1.0.36

package/src/services/db/stats.ts

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { DbInvalidArgumentError, DbResponseError } from './util.ts';
+
+// Request schema
+export const DbLogStatsRequestSchema = z.object({
+	database: z.string().describe('the database name'),
+	orgId: z.string().describe('the organization ID'),
+	region: z.string().describe('the region'),
+	startDate: z.string().describe('start date filter (ISO 8601)'),
+	endDate: z.string().describe('end date filter (ISO 8601)'),
+});
+
+// Summary stats
+export const DbLogStatsSummarySchema = z.object({
+	totalQueries: z.number().describe('total number of queries'),
+	errorCount: z.number().describe('number of queries with errors'),
+	avgDuration: z.number().describe('average query duration in ms'),
+	p50Duration: z.number().describe('50th percentile duration in ms'),
+	p95Duration: z.number().describe('95th percentile duration in ms'),
+	p99Duration: z.number().describe('99th percentile duration in ms'),
+	maxDuration: z.number().describe('maximum query duration in ms'),
+	totalRows: z.number().describe('total rows affected/returned'),
+});
+
+// Time series point
+export const DbLogStatsTimeSeriesPointSchema = z.object({
+	timestamp: z.string().describe('bucket timestamp'),
+	queryCount: z.number().describe('queries in this bucket'),
+	errorCount: z.number().describe('errors in this bucket'),
+	avgDuration: z.number().describe('average duration in this bucket'),
+	p50Duration: z.number().describe('p50 duration in this bucket'),
+	p95Duration: z.number().describe('p95 duration in this bucket'),
+	p99Duration: z.number().describe('p99 duration in this bucket'),
+});
+
+// Query pattern
+export const DbLogStatsQueryPatternSchema = z.object({
+	pattern: z.string().describe('SQL query text'),
+	command: z.string().describe('SQL command type'),
+	calls: z.number().describe('number of executions'),
+	avgDuration: z.number().describe('average duration in ms'),
+	p95Duration: z.number().describe('95th percentile duration in ms'),
+	maxDuration: z.number().describe('maximum duration in ms'),
+	totalDuration: z.number().describe('total cumulative duration in ms'),
+	avgRows: z.number().describe('average rows affected'),
+	errors: z.number().describe('number of errors'),
+});
+
+// Command breakdown
+export const DbLogStatsCommandBreakdownSchema = z.object({
+	command: z.string().describe('SQL command type'),
+	queryCount: z.number().describe('number of queries'),
+	avgDuration: z.number().describe('average duration in ms'),
+	p95Duration: z.number().describe('95th percentile duration in ms'),
+	totalDuration: z.number().describe('total cumulative duration in ms'),
+	errorCount: z.number().describe('number of errors'),
+});
+
+// Combined response
+export const DbLogStatsResponseSchema = z.object({
+	summary: DbLogStatsSummarySchema,
+	timeSeries: z.array(DbLogStatsTimeSeriesPointSchema),
+	queryPatterns: z.array(DbLogStatsQueryPatternSchema),
+	commandBreakdown: z.array(DbLogStatsCommandBreakdownSchema),
+});
+
+export const DbLogStatsAPIResponseSchema = APIResponseSchema(DbLogStatsResponseSchema);
+
+// Type exports
+export type DbLogStatsSummary = z.infer<typeof DbLogStatsSummarySchema>;
+export type DbLogStatsTimeSeriesPoint = z.infer<typeof DbLogStatsTimeSeriesPointSchema>;
+export type DbLogStatsQueryPattern = z.infer<typeof DbLogStatsQueryPatternSchema>;
+export type DbLogStatsCommandBreakdown = z.infer<typeof DbLogStatsCommandBreakdownSchema>;
+export type DbLogStatsResponse = z.infer<typeof DbLogStatsResponseSchema>;
+
+type DbLogStatsRequest = z.infer<typeof DbLogStatsRequestSchema>;
+type DbLogStatsAPIResponse = z.infer<typeof DbLogStatsAPIResponseSchema>;
+
+/**
+ * Get query performance stats for a database
+ */
+export async function dbLogStats(
+	client: APIClient,
+	request: DbLogStatsRequest
+): Promise<DbLogStatsResponse> {
+	if (!request) {
+		throw new DbInvalidArgumentError({
+			message: 'request is required',
+			orgId: undefined,
+			region: undefined,
+		});
+	}
+
+	const { database, orgId, region, startDate, endDate } = request;
+
+	if (!orgId || !region || !database || !startDate || !endDate) {
+		throw new DbInvalidArgumentError({
+			message: 'orgId, region, database, startDate, and endDate are required',
+			orgId,
+			region,
+		});
+	}
+
+	const params = new URLSearchParams();
+	params.append('startDate', startDate);
+	params.append('endDate', endDate);
+
+	const url = `/resource/${encodeURIComponent(orgId)}/${encodeURIComponent(region)}/${encodeURIComponent(database)}/logs/stats?${params.toString()}`;
+
+	const resp = await client.get<DbLogStatsAPIResponse>(url, DbLogStatsAPIResponseSchema);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new DbResponseError({
+		database,
+		message: resp.message || 'Failed to fetch database performance stats',
+	});
+}

package/src/services/keyvalue/service.ts

@@ -9,9 +9,9 @@ import { z } from 'zod';
 export const KV_MIN_TTL_SECONDS = 60;
 
 /**
- * Maximum TTL value in seconds (90 days)
+ * Maximum TTL value in seconds (365 days)
  */
-export const KV_MAX_TTL_SECONDS = 7776000;
+export const KV_MAX_TTL_SECONDS = 31536000;
 
 /**
  * Default TTL value in seconds (7 days) - used when namespace is auto-created or no TTL specified
@@ -88,11 +88,11 @@ export const KeyValueStorageSetParamsSchema = z.object({
 	 * Time-to-live in seconds for the key. Controls when the key expires and is automatically deleted.
 	 * - `undefined` (not provided): Key inherits the namespace's default TTL (7 days if not configured)
 	 * - `null` or `0`: Key never expires
-	 * - positive number (≥60): Key expires after the specified number of seconds (max 90 days)
+	 * - positive number (≥60): Key expires after the specified number of seconds (max 365 days)
 	 *
 	 * @remarks
 	 * TTL values below 60 seconds are clamped to 60 seconds by the server.
-	 * TTL values above 7,776,000 seconds (90 days) are clamped to 90 days.
+	 * TTL values above 31,536,000 seconds (365 days) are clamped to 365 days.
 	 */
 	ttl: z
 		.number()
@@ -117,7 +117,7 @@ export const CreateNamespaceParamsSchema = z.object({
 	 * Default TTL for keys in this namespace (in seconds).
 	 * - If undefined/omitted: uses server default (7 days / 604,800 seconds)
 	 * - If 0: keys will not expire by default
-	 * - If 60-7,776,000: custom TTL in seconds (1 minute to 90 days)
+	 * - If 60-31,536,000: custom TTL in seconds (1 minute to 365 days)
 	 *
 	 * Keys can override this default by specifying TTL in the set() call.
 	 * Active keys are automatically extended (sliding expiration) when read
@@ -444,7 +444,7 @@ export class KeyValueStorageService implements KeyValueStorage {
 	 * - If TTL is null or 0, the key will not expire
 	 * - If TTL is a positive number, the key expires after that many seconds
 	 * - TTL values below 60 seconds are clamped to 60 seconds by the server
-	 * - TTL values above 7,776,000 seconds (90 days) are clamped to 90 days
+	 * - TTL values above 31,536,000 seconds (365 days) are clamped to 365 days
 	 * - If the namespace doesn't exist, it is auto-created with a 7-day default TTL
 	 */
 	async set<T = unknown>(

package/src/services/queue/types.ts

@@ -1568,7 +1568,14 @@ export const ConsumerSchema = z
 	.object({
 		id: z.string().describe('Unique consumer identifier (qcns_ prefix).'),
 		queue_id: z.string().describe('Queue this consumer is connected to.'),
-		client_id: z.string().nullable().optional().describe('Client-provided ID for reconnection.'),
+		client_id: z
+			.string()
+			.max(256)
+			.nullable()
+			.optional()
+			.describe(
+				'Client-provided identifier (max 256 characters). Can be any string for your own identification purposes.'
+			),
 		durable: z.boolean().describe('Whether this consumer uses durable offset tracking.'),
 		ip_address: z.string().nullable().optional().describe('IP address of the consumer.'),
 		last_offset: z.number().nullable().optional().describe('Last processed message offset.'),
@@ -1603,8 +1610,11 @@ export const WebSocketAuthRequestSchema = z
 			.describe('The API key for authentication (raw key, not "Bearer ...").'),
 		client_id: z
 			.string()
+			.max(256)
 			.optional()
-			.describe('Optional client ID from a previous connection for reconnection.'),
+			.describe(
+				'Optional client identifier (max 256 characters). Can be any string for your own identification purposes. If omitted, the server generates one. Store and reuse on reconnect for resume semantics.'
+			),
 		last_offset: z
 			.number()
 			.optional()

package/src/services/queue/websocket.ts

@@ -58,9 +58,9 @@
  */
 
 import { z } from 'zod';
+import { getEnv } from '../env.ts';
 import type { Message } from './types.ts';
 import { WebSocketAuthResponseSchema, WebSocketMessageSchema } from './types.ts';
-import { getEnv } from '../env.ts';
 import { QueueError } from './util.ts';
 import { validateQueueName } from './validation.ts';
 
@@ -106,7 +106,13 @@ export const QueueWebSocketOptionsSchema = z.object({
 		.describe('Maximum reconnect attempts before giving up'),
 	reconnectDelayMs: z.number().optional().describe('Initial reconnect delay in milliseconds'),
 	maxReconnectDelayMs: z.number().optional().describe('Maximum reconnect delay in milliseconds'),
-	clientId: z.string().optional().describe('Optional prior client id used for resume semantics'),
+	clientId: z
+		.string()
+		.max(256)
+		.optional()
+		.describe(
+			'Optional client identifier (max 256 characters). Can be any string for your own identification. Reuse on reconnect for resume semantics.'
+		),
 	lastOffset: z
 		.number()
 		.optional()
@@ -140,7 +146,13 @@ export const SubscribeToQueueOptionsSchema = z.object({
 		.describe('Optional API key override; falls back to AGENTUITY_SDK_KEY'),
 	baseUrl: z.string().describe('Base Catalyst URL used to construct the WebSocket endpoint'),
 	signal: z.custom<AbortSignal>().optional().describe('AbortSignal used to stop the subscription'),
-	clientId: z.string().optional().describe('Optional prior client id used for resume semantics'),
+	clientId: z
+		.string()
+		.max(256)
+		.optional()
+		.describe(
+			'Optional client identifier (max 256 characters). Can be any string for your own identification. Reuse on reconnect for resume semantics.'
+		),
 	lastOffset: z
 		.number()
 		.optional()
@@ -227,7 +239,7 @@ export function createQueueWebSocket(options: QueueWebSocketOptions): QueueWebSo
 		onClose,
 		onError,
 		autoReconnect = true,
-		maxReconnectAttempts = Infinity,
+		maxReconnectAttempts = Number.POSITIVE_INFINITY,
 		reconnectDelayMs = 1000,
 		maxReconnectDelayMs = 30000,
 		orgId,
@@ -349,6 +361,12 @@ export function createQueueWebSocket(options: QueueWebSocketOptions): QueueWebSo
 			state = 'closed';
 			ws = null;
 
+			// Close codes 4000–4999 are application-level terminal errors
+			// (auth failure, validation error, etc.) — do not reconnect.
+			if (event.code >= 4000 && event.code < 5000) {
+				intentionallyClosed = true;
+			}
+
 			onClose?.(event.code, event.reason);
 
 			// Reconnect on any unintentional close — whether we were fully
@@ -383,7 +401,7 @@ export function createQueueWebSocket(options: QueueWebSocketOptions): QueueWebSo
 		}
 
 		// Exponential backoff with jitter, capped at maxReconnectDelayMs.
-		const baseDelay = reconnectDelayMs * Math.pow(2, reconnectAttempts);
+		const baseDelay = reconnectDelayMs * 2 ** reconnectAttempts;
 		const jitter = 0.5 + Math.random() * 0.5;
 		const delay = Math.min(Math.floor(baseDelay * jitter), maxReconnectDelayMs);
 
@@ -508,9 +526,15 @@ export async function* subscribeToQueue(
 				// it to be thrown on clean shutdown / abort.
 			}
 		},
-		onClose: () => {
-			// Only finish if the connection is intentionally closed (signal aborted).
-			// Otherwise, the callback-based API handles reconnection.
+		onClose: (code: number) => {
+			// Terminal close codes (4000–4999) mean the connection will not
+			// reconnect — signal the async iterator to stop so it doesn't
+			// hang forever.  For abort-initiated closes, `finish()` is
+			// already called by the `onAbort` handler; calling it again is
+			// harmless (it's idempotent).
+			if (code >= 4000 && code < 5000) {
+				finish();
+			}
 		},
 		autoReconnect: true,
 	});

package/src/services/sandbox/types.ts

@@ -130,7 +130,6 @@ const SandboxSnapshotInfoBaseSchema = z.object({
 	/** Full name with org slug (@slug/name:tag) */
 	fullName: z.string().optional().describe('Full name with org slug (@slug/name:tag)'),
 });
-type SandboxSnapshotInfoBase = z.infer<typeof SandboxSnapshotInfoBaseSchema>;
 
 /** Public snapshot information - includes org info */
 export const SandboxSnapshotInfoPublicSchema = SandboxSnapshotInfoBaseSchema.extend({

package/src/services/webhook/analytics.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import {
+	type WebhookAnalyticsOptions,
+	type WebhookOrgAnalytics,
+	WebhookOrgAnalyticsSchema,
+	type WebhookTimeSeriesData,
+	WebhookTimeSeriesDataSchema,
+} from './types.ts';
+import { buildWebhookHeaders, WebhookError, webhookApiPathWithQuery } from './util.ts';
+
+export const WebhookOrgAnalyticsResponseSchema = APIResponseSchema(
+	z.object({ analytics: WebhookOrgAnalyticsSchema })
+);
+
+export const WebhookTimeSeriesResponseSchema = APIResponseSchema(
+	z.object({ timeseries: WebhookTimeSeriesDataSchema })
+);
+
+function buildAnalyticsQuery(options?: WebhookAnalyticsOptions): string | undefined {
+	if (!options) return undefined;
+	const params = new URLSearchParams();
+	if (options.start) params.set('start', options.start);
+	if (options.end) params.set('end', options.end);
+	if (options.granularity) params.set('granularity', options.granularity);
+	const query = params.toString();
+	return query || undefined;
+}
+
+/**
+ * Get org-level webhook analytics summary.
+ *
+ * Returns total received, delivered, and failed counts for all webhooks in the org
+ * within the specified time period.
+ *
+ * @param client - The API client
+ * @param options - Analytics options (start, end, granularity)
+ * @returns Org-level webhook analytics
+ */
+export async function getWebhookOrgAnalytics(
+	client: APIClient,
+	options?: WebhookAnalyticsOptions
+): Promise<WebhookOrgAnalytics> {
+	const queryString = buildAnalyticsQuery(options);
+	const url = webhookApiPathWithQuery('analytics/org', queryString);
+	const resp = await client.get(
+		url,
+		WebhookOrgAnalyticsResponseSchema,
+		undefined,
+		buildWebhookHeaders(options?.orgId)
+	);
+	if (resp.success) return resp.data.analytics;
+	throw new WebhookError({ message: resp.message || 'Failed to get webhook org analytics' });
+}
+
+/**
+ * Get org-level webhook time series data.
+ *
+ * Returns time-bucketed received, delivered, and failed counts for all webhooks
+ * in the org within the specified time period.
+ *
+ * @param client - The API client
+ * @param options - Analytics options (start, end, granularity)
+ * @returns Webhook time series data
+ */
+export async function getWebhookOrgTimeSeries(
+	client: APIClient,
+	options?: WebhookAnalyticsOptions
+): Promise<WebhookTimeSeriesData> {
+	const queryString = buildAnalyticsQuery(options);
+	const url = webhookApiPathWithQuery('analytics/org/timeseries', queryString);
+	const resp = await client.get(
+		url,
+		WebhookTimeSeriesResponseSchema,
+		undefined,
+		buildWebhookHeaders(options?.orgId)
+	);
+	if (resp.success) return resp.data.timeseries;
+	throw new WebhookError({ message: resp.message || 'Failed to get webhook org time series' });
+}

package/src/services/webhook/index.ts

@@ -68,6 +68,20 @@ export {
 	WebhookDestinationTypeSchema,
 	type WebhookReceipt,
 	WebhookReceiptSchema,
+	type WebhookAnalyticsGranularity,
+	WebhookAnalyticsGranularitySchema,
+	type WebhookAnalyticsOptions,
+	WebhookAnalyticsOptionsSchema,
+	type WebhookAnalyticsSummary,
+	WebhookAnalyticsSummarySchema,
+	type WebhookOrgAnalytics,
+	WebhookOrgAnalyticsSchema,
+	type WebhookTimePeriod,
+	WebhookTimePeriodSchema,
+	type WebhookTimeSeriesData,
+	WebhookTimeSeriesDataSchema,
+	type WebhookTimeSeriesPoint,
+	WebhookTimeSeriesPointSchema,
 	WebhookSchema,
 } from './types.ts';
 
@@ -133,3 +147,14 @@ export {
 	WebhookDeliveriesListResponseSchema,
 	WebhookDeliveryResponseSchema,
 } from './deliveries.ts';
+
+// ============================================================================
+// Analytics Operations
+// ============================================================================
+
+export {
+	getWebhookOrgAnalytics,
+	getWebhookOrgTimeSeries,
+	WebhookOrgAnalyticsResponseSchema,
+	WebhookTimeSeriesResponseSchema,
+} from './analytics.ts';

package/src/services/webhook/service.ts

@@ -8,6 +8,7 @@ import type {
 	Webhook,
 	WebhookDelivery,
 	WebhookDestination,
+	WebhookOrgAnalytics,
 	WebhookReceipt,
 } from './types.ts';
 
@@ -773,4 +774,127 @@ export class WebhookService {
 
 		throw await toServiceException('POST', url, res.response);
 	}
+
+	/**
+	 * Get org-level webhook analytics summary.
+	 *
+	 * Returns total received, delivered, and failed counts for all webhooks
+	 * in the org within the specified time period.
+	 *
+	 * @param options - Analytics options (start, end, granularity)
+	 * @returns Org-level webhook analytics with period and summary
+	 * @throws {@link ServiceException} if the API request fails
+	 */
+	async getOrgAnalytics(options?: {
+		start?: string;
+		end?: string;
+		granularity?: string;
+	}): Promise<WebhookOrgAnalytics> {
+		const params = new URLSearchParams();
+		if (options?.start) params.set('start', options.start);
+		if (options?.end) params.set('end', options.end);
+		if (options?.granularity) params.set('granularity', options.granularity);
+		const query = params.toString();
+		const path = query ? `/webhook/analytics/org?${query}` : '/webhook/analytics/org';
+		const url = buildUrl(this.#baseUrl, path);
+		const signal = createTimeoutSignal();
+		const res = await this.#adapter.invoke<
+			WebhookResponse<{
+				analytics: {
+					period: { start: string; end: string };
+					summary: { total_received: number; total_delivered: number; total_failed: number };
+				};
+			}>
+		>(url, {
+			method: 'GET',
+			signal,
+			telemetry: { name: 'agentuity.webhook.analytics.org' },
+		});
+
+		if (res.ok) {
+			if (res.data.success) {
+				const unwrapped = this.#unwrap<{
+					analytics: {
+						period: { start: string; end: string };
+						summary: {
+							total_received: number;
+							total_delivered: number;
+							total_failed: number;
+						};
+					};
+				}>(res.data.data);
+				return unwrapped.analytics;
+			}
+			throw new WebhookResponseError({ status: res.response.status, message: res.data.message });
+		}
+
+		throw await toServiceException('GET', url, res.response);
+	}
+
+	/**
+	 * Get org-level webhook time series data.
+	 *
+	 * Returns time-bucketed received, delivered, and failed counts for all webhooks
+	 * in the org within the specified time period.
+	 *
+	 * @param options - Analytics options (start, end, granularity)
+	 * @returns Webhook time series data with period and series array
+	 * @throws {@link ServiceException} if the API request fails
+	 */
+	async getOrgTimeSeries(options?: {
+		start?: string;
+		end?: string;
+		granularity?: string;
+	}): Promise<{
+		period: { start: string; end: string; granularity?: string };
+		series: Array<{ timestamp: string; received: number; delivered: number; failed: number }>;
+	}> {
+		const params = new URLSearchParams();
+		if (options?.start) params.set('start', options.start);
+		if (options?.end) params.set('end', options.end);
+		if (options?.granularity) params.set('granularity', options.granularity);
+		const query = params.toString();
+		const path = query
+			? `/webhook/analytics/org/timeseries?${query}`
+			: '/webhook/analytics/org/timeseries';
+		const url = buildUrl(this.#baseUrl, path);
+		const signal = createTimeoutSignal();
+		const res = await this.#adapter.invoke<
+			WebhookResponse<{
+				timeseries: {
+					period: { start: string; end: string; granularity?: string };
+					series: Array<{
+						timestamp: string;
+						received: number;
+						delivered: number;
+						failed: number;
+					}>;
+				};
+			}>
+		>(url, {
+			method: 'GET',
+			signal,
+			telemetry: { name: 'agentuity.webhook.analytics.org.timeseries' },
+		});
+
+		if (res.ok) {
+			if (res.data.success) {
+				const unwrapped = this.#unwrap<{
+					timeseries: {
+						period: { start: string; end: string; granularity?: string };
+						series: Array<{
+							timestamp: string;
+							received: number;
+							delivered: number;
+							failed: number;
+						}>;
+					};
+				}>(res.data.data);
+				return unwrapped.timeseries;
+			}
+			throw new WebhookResponseError({ status: res.response.status, message: res.data.message });
+		}
+
+		throw await toServiceException('GET', url, res.response);
+	}
 }

package/src/services/webhook/types.ts

@@ -40,6 +40,17 @@ export const WebhookSchema = z
 			.describe(
 				'Fully-qualified ingest URL for sending events to this webhook. Only present on create'
 			),
+		internal: z
+			.boolean()
+			.describe(
+				'Whether this is a system-managed webhook (e.g., S3 bucket notifications). Internal webhooks cannot be modified or deleted by users'
+			),
+		metadata: z
+			.record(z.string(), z.unknown())
+			.nullable()
+			.describe(
+				'System metadata for internal webhooks (e.g., bucket_name, type). Null for user-created webhooks'
+			),
 	})
 	.describe('Webhook endpoint configuration');
 
@@ -56,6 +67,17 @@ export const WebhookDestinationSchema = z
 		config: z
 			.record(z.string(), z.unknown())
 			.describe('Configuration object for the destination (e.g., URL, headers)'),
+		internal: z
+			.boolean()
+			.describe(
+				'Whether this is a system-managed destination. Internal destinations cannot be modified or deleted by users'
+			),
+		metadata: z
+			.record(z.string(), z.unknown())
+			.nullable()
+			.describe(
+				'System metadata for internal destinations (e.g., bucket_name, type). Null for user-created destinations'
+			),
 	})
 	.describe('Webhook destination representing a delivery target for webhook events');
 
@@ -98,6 +120,76 @@ export const WebhookDeliverySchema = z
 
 export type WebhookDelivery = z.infer<typeof WebhookDeliverySchema>;
 
+// ============================================================================
+// Analytics Types
+// ============================================================================
+
+export const WebhookAnalyticsGranularitySchema = z
+	.enum(['minute', 'hour', 'day'])
+	.describe('Time bucket granularity for analytics queries');
+
+export type WebhookAnalyticsGranularity = z.infer<typeof WebhookAnalyticsGranularitySchema>;
+
+export const WebhookAnalyticsOptionsSchema = z
+	.object({
+		start: z.string().optional().describe('ISO 8601 start time for the analytics window'),
+		end: z.string().optional().describe('ISO 8601 end time for the analytics window'),
+		granularity: WebhookAnalyticsGranularitySchema.optional().describe('Time bucket granularity'),
+		orgId: z.string().optional().describe('Organization ID for CLI-authenticated requests'),
+	})
+	.describe('Options for webhook analytics queries');
+
+export type WebhookAnalyticsOptions = z.infer<typeof WebhookAnalyticsOptionsSchema>;
+
+export const WebhookTimePeriodSchema = z
+	.object({
+		start: z.string().describe('ISO 8601 start time'),
+		end: z.string().describe('ISO 8601 end time'),
+		granularity: WebhookAnalyticsGranularitySchema.optional(),
+	})
+	.describe('Time period for analytics data');
+
+export type WebhookTimePeriod = z.infer<typeof WebhookTimePeriodSchema>;
+
+export const WebhookAnalyticsSummarySchema = z
+	.object({
+		total_received: z.number().describe('Total webhook receipts in the period'),
+		total_delivered: z.number().describe('Total successful deliveries in the period'),
+		total_failed: z.number().describe('Total failed deliveries in the period'),
+	})
+	.describe('Summary analytics for webhook activity');
+
+export type WebhookAnalyticsSummary = z.infer<typeof WebhookAnalyticsSummarySchema>;
+
+export const WebhookOrgAnalyticsSchema = z
+	.object({
+		period: WebhookTimePeriodSchema,
+		summary: WebhookAnalyticsSummarySchema,
+	})
+	.describe('Org-level webhook analytics response');
+
+export type WebhookOrgAnalytics = z.infer<typeof WebhookOrgAnalyticsSchema>;
+
+export const WebhookTimeSeriesPointSchema = z
+	.object({
+		timestamp: z.string().describe('ISO 8601 timestamp for this data point'),
+		received: z.number().describe('Number of receipts in this bucket'),
+		delivered: z.number().describe('Number of successful deliveries in this bucket'),
+		failed: z.number().describe('Number of failed deliveries in this bucket'),
+	})
+	.describe('Single data point in webhook time series');
+
+export type WebhookTimeSeriesPoint = z.infer<typeof WebhookTimeSeriesPointSchema>;
+
+export const WebhookTimeSeriesDataSchema = z
+	.object({
+		period: WebhookTimePeriodSchema,
+		series: z.array(WebhookTimeSeriesPointSchema),
+	})
+	.describe('Webhook time series analytics data');
+
+export type WebhookTimeSeriesData = z.infer<typeof WebhookTimeSeriesDataSchema>;
+
 // ============================================================================
 // API Options
 // ============================================================================