zorihq 0.6.0 → 0.8.0

package/src/resources/v1/analytics/analytics.ts

@@ -2,7 +2,7 @@
 
 import { APIResource } from '../../../core/resource';
 import * as EventsAPI from './events';
-import { EventRecentParams, Events } from './events';
+import { EventFilterOptionsParams, EventRecentParams, Events } from './events';
 import * as RetentionAPI from './retention';
 import {
   Retention,
@@ -10,6 +10,8 @@ import {
   RetentionCohortsParams,
   RetentionReturnRateParams,
 } from './retention';
+import * as RevenueAPI from './revenue';
+import { Revenue, RevenueByUtmParams, RevenueTimelineParams } from './revenue';
 import * as SessionsAPI from './sessions';
 import { SessionBounceRateParams, SessionMetricsParams, Sessions } from './sessions';
 import * as UsersAPI from './users';
@@ -19,6 +21,7 @@ import {
   VisitorByCountryParams,
   VisitorByDeviceParams,
   VisitorByOriginParams,
+  VisitorIdentifyParams,
   VisitorProfileParams,
   VisitorTimelineParams,
   VisitorTopParams,
@@ -30,6 +33,7 @@ import { RequestOptions } from '../../../internal/request-options';
 export class Analytics extends APIResource {
   visitors: VisitorsAPI.Visitors = new VisitorsAPI.Visitors(this._client);
   events: EventsAPI.Events = new EventsAPI.Events(this._client);
+  revenue: RevenueAPI.Revenue = new RevenueAPI.Revenue(this._client);
   sessions: SessionsAPI.Sessions = new SessionsAPI.Sessions(this._client);
   users: UsersAPI.Users = new UsersAPI.Users(this._client);
   retention: RetentionAPI.Retention = new RetentionAPI.Retention(this._client);
@@ -117,6 +121,21 @@ export interface CountryDataPoint {
 export interface DashboardMetricsResponse {
   avg_pages_per_session?: number;
 
+  /**
+   * Average revenue for identified visitors only (deprecated)
+   */
+  avg_revenue_per_identified_customer?: number;
+
+  /**
+   * 3. Average revenue per unique session
+   */
+  avg_revenue_per_session?: number;
+
+  /**
+   * Average revenue per paying visitor
+   */
+  avg_revenue_per_visitor?: number;
+
   avg_session_duration_seconds?: number;
 
   /**
@@ -124,6 +143,18 @@ export interface DashboardMetricsResponse {
    */
   bounce_rate?: number;
 
+  /**
+   * 4. % of unique visitors who made payment
+   */
+  conversion_rate?: number;
+
+  /**
+   * Same as ConversionRate (deprecated, use ConversionRate)
+   */
+  conversion_to_paying?: number;
+
+  currency?: string;
+
   /**
    * Active users
    */
@@ -131,6 +162,11 @@ export interface DashboardMetricsResponse {
 
   mau?: number;
 
+  /**
+   * Additional revenue metrics (kept for compatibility)
+   */
+  paying_visitors?: number;
+
   return_rate?: number;
 
   /**
@@ -143,24 +179,105 @@ export interface DashboardMetricsResponse {
    */
   total_events?: number;
 
+  /**
+   * Count of successful payments
+   */
+  total_payments?: number;
+
+  /**
+   * Revenue metrics - 4 key metrics as separate queries
+   */
+  total_revenue?: number;
+
+  /**
+   * 2. Total revenue for identified customers only
+   */
+  total_revenue_identified_customers?: number;
+
   total_sessions_in_period?: number;
 
+  /**
+   * Total unique sessions in period
+   */
+  unique_sessions?: number;
+
   unique_visitors?: number;
 
   wau?: number;
 }
 
+export interface EventFilterOptionsResponse {
+  /**
+   * Unique page paths
+   */
+  pages?: Array<string>;
+
+  /**
+   * Unique referrer domains
+   */
+  traffic_origins?: Array<string>;
+}
+
 export interface EventsOverTimeDataPoint {
   event_count?: number;
 
   timestamp?: string;
 }
 
+export interface ManualIdentifyRequest {
+  project_id: string;
+
+  visitor_id: string;
+
+  additional_properties?: { [key: string]: unknown };
+
+  email?: string;
+
+  external_id?: string;
+
+  name?: string;
+
+  phone?: string;
+
+  user_id?: string;
+}
+
+export interface ManualIdentifyResponse {
+  message?: string;
+
+  success?: boolean;
+
+  visitor_id?: string;
+}
+
 export interface OriginDataPoint {
+  /**
+   * Average revenue per paying visitor
+   */
+  avg_revenue_per_visitor?: number;
+
+  /**
+   * paying_visitors / unique_visitors \* 100
+   */
+  conversion_rate?: number;
+
+  currency?: string;
+
   origin?: string;
 
+  paying_visitors?: number;
+
+  payment_count?: number;
+
   percentage?: number;
 
+  revenue_percentage?: number;
+
+  /**
+   * Revenue in smallest currency unit (cents)
+   */
+  total_revenue?: number;
+
   unique_visitors?: number;
 }
 
@@ -173,22 +290,36 @@ export interface RecentEvent {
 
   event_name?: string;
 
+  external_id?: string;
+
   location_city?: string;
 
   location_country_iso?: string;
 
+  location_latitude?: number;
+
+  location_longitude?: number;
+
   page_path?: string;
 
   page_url?: string;
 
+  referrer_domain?: string;
+
   referrer_url?: string;
 
+  user_id?: string;
+
   visitor_id?: string;
 }
 
 export interface RecentEventsResponse {
   events?: Array<RecentEvent>;
 
+  limit?: number;
+
+  offset?: number;
+
   total?: number;
 }
 
@@ -202,6 +333,27 @@ export interface ReturnRateResponse {
   total_users?: number;
 }
 
+export interface RevenueByUtmResponse {
+  data?: Array<UtmRevenueDataPoint>;
+}
+
+export interface RevenueTimelineDataPoint {
+  currency?: string;
+
+  payment_count?: number;
+
+  timestamp?: string;
+
+  /**
+   * Revenue in smallest currency unit (cents)
+   */
+  total_revenue?: number;
+}
+
+export interface RevenueTimelineResponse {
+  data?: Array<RevenueTimelineDataPoint>;
+}
+
 export interface SessionMetricsResponse {
   average_pages_per_session?: number;
 
@@ -213,10 +365,14 @@ export interface SessionMetricsResponse {
 export interface TopVisitor {
   browser_name?: string;
 
+  currency?: string;
+
   device_type?: string;
 
   event_count?: number;
 
+  external_id?: string;
+
   first_seen?: string;
 
   last_seen?: string;
@@ -225,6 +381,15 @@ export interface TopVisitor {
 
   location_country_iso?: string;
 
+  payment_count?: number;
+
+  /**
+   * Total revenue in smallest currency unit (cents)
+   */
+  total_revenue?: number;
+
+  user_id?: string;
+
   visitor_id?: string;
 }
 
@@ -246,6 +411,38 @@ export interface UniqueVisitorsTimelineResponse {
   data?: Array<UniqueVisitorsDataPoint>;
 }
 
+export interface UtmRevenueDataPoint {
+  /**
+   * Average revenue per paying visitor
+   */
+  avg_revenue_per_visitor?: number;
+
+  /**
+   * paying_visitors / unique_visitors \* 100
+   */
+  conversion_rate?: number;
+
+  currency?: string;
+
+  paying_visitors?: number;
+
+  payment_count?: number;
+
+  revenue_percentage?: number;
+
+  /**
+   * Revenue in smallest currency unit (cents)
+   */
+  total_revenue?: number;
+
+  unique_visitors?: number;
+
+  /**
+   * The UTM parameter value
+   */
+  utm_value?: string;
+}
+
 export interface VisitorDataPoint {
   desktop?: number;
 
@@ -272,25 +469,79 @@ export interface VisitorEvent {
   referrer_url?: string;
 }
 
+export interface VisitorPayment {
+  amount?: number;
+
+  currency?: string;
+
+  payment_id?: string;
+
+  payment_timestamp?: string;
+
+  product_name?: string;
+
+  provider_type?: string;
+
+  status?: string;
+}
+
 export interface VisitorProfileResponse {
+  /**
+   * Average payment amount
+   */
+  avg_order_value?: number;
+
+  currency?: string;
+
+  custom_traits?: { [key: string]: unknown };
+
+  email?: string;
+
   events?: Array<VisitorEvent>;
 
   events_over_time?: Array<EventsOverTimeDataPoint>;
 
+  external_id?: string;
+
+  first_identified_at?: string;
+
+  first_payment_date?: string;
+
   first_referrer_url?: string;
 
   first_seen?: string;
 
   first_traffic_origin?: string;
 
+  is_identified?: boolean;
+
+  last_identified_at?: string;
+
+  last_payment_date?: string;
+
   last_seen?: string;
 
   location_city?: string;
 
   location_country_iso?: string;
 
+  name?: string;
+
+  payment_count?: number;
+
+  payments?: Array<VisitorPayment>;
+
+  phone?: string;
+
   total_events?: number;
 
+  /**
+   * Revenue fields
+   */
+  total_revenue?: number;
+
+  user_id?: string;
+
   visitor_id?: string;
 }
 
@@ -320,6 +571,7 @@ export interface AnalyticsDashboardParams {
 
 Analytics.Visitors = Visitors;
 Analytics.Events = Events;
+Analytics.Revenue = Revenue;
 Analytics.Sessions = Sessions;
 Analytics.Users = Users;
 Analytics.Retention = Retention;
@@ -334,18 +586,26 @@ export declare namespace Analytics {
     type CohortData as CohortData,
     type CountryDataPoint as CountryDataPoint,
     type DashboardMetricsResponse as DashboardMetricsResponse,
+    type EventFilterOptionsResponse as EventFilterOptionsResponse,
     type EventsOverTimeDataPoint as EventsOverTimeDataPoint,
+    type ManualIdentifyRequest as ManualIdentifyRequest,
+    type ManualIdentifyResponse as ManualIdentifyResponse,
     type OriginDataPoint as OriginDataPoint,
     type RecentEvent as RecentEvent,
     type RecentEventsResponse as RecentEventsResponse,
     type ReturnRateResponse as ReturnRateResponse,
+    type RevenueByUtmResponse as RevenueByUtmResponse,
+    type RevenueTimelineDataPoint as RevenueTimelineDataPoint,
+    type RevenueTimelineResponse as RevenueTimelineResponse,
     type SessionMetricsResponse as SessionMetricsResponse,
     type TopVisitor as TopVisitor,
     type TopVisitorsResponse as TopVisitorsResponse,
     type UniqueVisitorsDataPoint as UniqueVisitorsDataPoint,
     type UniqueVisitorsTimelineResponse as UniqueVisitorsTimelineResponse,
+    type UtmRevenueDataPoint as UtmRevenueDataPoint,
     type VisitorDataPoint as VisitorDataPoint,
     type VisitorEvent as VisitorEvent,
+    type VisitorPayment as VisitorPayment,
     type VisitorProfileResponse as VisitorProfileResponse,
     type VisitorsByCountryResponse as VisitorsByCountryResponse,
     type VisitorsByDeviceResponse as VisitorsByDeviceResponse,
@@ -358,12 +618,23 @@ export declare namespace Analytics {
     type VisitorByCountryParams as VisitorByCountryParams,
     type VisitorByDeviceParams as VisitorByDeviceParams,
     type VisitorByOriginParams as VisitorByOriginParams,
+    type VisitorIdentifyParams as VisitorIdentifyParams,
     type VisitorProfileParams as VisitorProfileParams,
     type VisitorTimelineParams as VisitorTimelineParams,
     type VisitorTopParams as VisitorTopParams,
   };
 
-  export { Events as Events, type EventRecentParams as EventRecentParams };
+  export {
+    Events as Events,
+    type EventFilterOptionsParams as EventFilterOptionsParams,
+    type EventRecentParams as EventRecentParams,
+  };
+
+  export {
+    Revenue as Revenue,
+    type RevenueByUtmParams as RevenueByUtmParams,
+    type RevenueTimelineParams as RevenueTimelineParams,
+  };
 
   export {
     Sessions as Sessions,

package/src/resources/v1/analytics/events.ts

@@ -7,7 +7,26 @@ import { RequestOptions } from '../../../internal/request-options';
 
 export class Events extends APIResource {
   /**
-   * Get a list of the most recent events (default: 15 events)
+   * Get unique traffic origins and page paths to populate filter dropdowns
+   *
+   * @example
+   * ```ts
+   * const eventFilterOptionsResponse =
+   *   await client.v1.analytics.events.filterOptions({
+   *     project_id: 'project_id',
+   *   });
+   * ```
+   */
+  filterOptions(
+    query: EventFilterOptionsParams,
+    options?: RequestOptions,
+  ): APIPromise<AnalyticsAPI.EventFilterOptionsResponse> {
+    return this._client.get('/api/v1/analytics/events/filter-options', { query, ...options });
+  }
+
+  /**
+   * Get a list of recent events with optional filters (visitor_id, user_id,
+   * external_id, traffic_origin, page_path)
    *
    * @example
    * ```ts
@@ -22,18 +41,63 @@ export class Events extends APIResource {
   }
 }
 
+export interface EventFilterOptionsParams {
+  /**
+   * Project ID
+   */
+  project_id: string;
+
+  /**
+   * Time range
+   */
+  time_range?: 'last_hour' | 'today' | 'last_7_days' | 'last_30_days' | 'last_90_days';
+}
+
 export interface EventRecentParams {
   /**
    * Project ID
    */
   project_id: string;
 
+  /**
+   * Filter by external ID
+   */
+  external_id?: string;
+
   /**
    * Maximum number of events to return (default: 15)
    */
   limit?: number;
+
+  /**
+   * Offset for pagination (default: 0)
+   */
+  offset?: number;
+
+  /**
+   * Filter by page path
+   */
+  page_path?: string;
+
+  /**
+   * Filter by traffic origin (referrer domain)
+   */
+  traffic_origin?: string;
+
+  /**
+   * Filter by user ID
+   */
+  user_id?: string;
+
+  /**
+   * Filter by visitor ID
+   */
+  visitor_id?: string;
 }
 
 export declare namespace Events {
-  export { type EventRecentParams as EventRecentParams };
+  export {
+    type EventFilterOptionsParams as EventFilterOptionsParams,
+    type EventRecentParams as EventRecentParams,
+  };
 }

package/src/resources/v1/analytics/index.ts

@@ -10,31 +10,40 @@ export {
   type CohortData,
   type CountryDataPoint,
   type DashboardMetricsResponse,
+  type EventFilterOptionsResponse,
   type EventsOverTimeDataPoint,
+  type ManualIdentifyRequest,
+  type ManualIdentifyResponse,
   type OriginDataPoint,
   type RecentEvent,
   type RecentEventsResponse,
   type ReturnRateResponse,
+  type RevenueByUtmResponse,
+  type RevenueTimelineDataPoint,
+  type RevenueTimelineResponse,
   type SessionMetricsResponse,
   type TopVisitor,
   type TopVisitorsResponse,
   type UniqueVisitorsDataPoint,
   type UniqueVisitorsTimelineResponse,
+  type UtmRevenueDataPoint,
   type VisitorDataPoint,
   type VisitorEvent,
+  type VisitorPayment,
   type VisitorProfileResponse,
   type VisitorsByCountryResponse,
   type VisitorsByDeviceResponse,
   type VisitorsByOriginResponse,
   type AnalyticsDashboardParams,
 } from './analytics';
-export { Events, type EventRecentParams } from './events';
+export { Events, type EventFilterOptionsParams, type EventRecentParams } from './events';
 export {
   Retention,
   type RetentionChurnRateParams,
   type RetentionCohortsParams,
   type RetentionReturnRateParams,
 } from './retention';
+export { Revenue, type RevenueByUtmParams, type RevenueTimelineParams } from './revenue';
 export { Sessions, type SessionBounceRateParams, type SessionMetricsParams } from './sessions';
 export { Users, type UserActiveParams } from './users';
 export {
@@ -42,6 +51,7 @@ export {
   type VisitorByCountryParams,
   type VisitorByDeviceParams,
   type VisitorByOriginParams,
+  type VisitorIdentifyParams,
   type VisitorProfileParams,
   type VisitorTimelineParams,
   type VisitorTopParams,

package/src/resources/v1/analytics/revenue.ts

@@ -0,0 +1,79 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as AnalyticsAPI from './analytics';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+
+export class Revenue extends APIResource {
+  /**
+   * Get revenue metrics grouped by UTM source, medium, or campaign
+   *
+   * @example
+   * ```ts
+   * const revenueByUtmResponse =
+   *   await client.v1.analytics.revenue.byUtm({
+   *     project_id: 'project_id',
+   *     time_range: 'last_hour',
+   *   });
+   * ```
+   */
+  byUtm(query: RevenueByUtmParams, options?: RequestOptions): APIPromise<AnalyticsAPI.RevenueByUtmResponse> {
+    return this._client.get('/api/v1/analytics/revenue/by-utm', { query, ...options });
+  }
+
+  /**
+   * Get revenue metrics over time for chart visualization
+   *
+   * @example
+   * ```ts
+   * const revenueTimelineResponse =
+   *   await client.v1.analytics.revenue.timeline({
+   *     project_id: 'project_id',
+   *     time_range: 'last_hour',
+   *   });
+   * ```
+   */
+  timeline(
+    query: RevenueTimelineParams,
+    options?: RequestOptions,
+  ): APIPromise<AnalyticsAPI.RevenueTimelineResponse> {
+    return this._client.get('/api/v1/analytics/revenue/timeline', { query, ...options });
+  }
+}
+
+export interface RevenueByUtmParams {
+  /**
+   * Project ID
+   */
+  project_id: string;
+
+  /**
+   * Time range
+   */
+  time_range: 'last_hour' | 'today' | 'last_7_days' | 'last_30_days' | 'last_90_days';
+
+  /**
+   * UTM type: source, medium, or campaign (default: source)
+   */
+  utm_type?: string;
+}
+
+export interface RevenueTimelineParams {
+  /**
+   * Project ID
+   */
+  project_id: string;
+
+  /**
+   * Time range
+   */
+  time_range: 'last_hour' | 'today' | 'last_7_days' | 'last_30_days' | 'last_90_days';
+}
+
+export declare namespace Revenue {
+  export {
+    type RevenueByUtmParams as RevenueByUtmParams,
+    type RevenueTimelineParams as RevenueTimelineParams,
+  };
+}