@agentuity/core 1.0.34 → 1.0.35

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
 // ============================================================================