types.go

// Package notificationapi provides types and structures for the NotificationAPI Go SDK
package notificationapi

// Region represents different geographical API endpoints
type Region string

const (
	// USRegion represents the United States region endpoint
	USRegion Region = "https://api.notificationapi.com"
	// EURegion represents the European Union region endpoint
	EURegion Region = "https://api.eu.notificationapi.com"
	// CARegion represents the Canada region endpoint
	CARegion Region = "https://api.ca.notificationapi.com"
)

// InitConfiguration contains configuration options for initializing the SDK
type InitConfiguration struct {
	// BaseURL allows overriding the base URL. Can be a region constant or custom URL string
	BaseURL string `json:"baseURL,omitempty"`
}

// Channels represents supported notification channels
type Channels string

const (
	// EMAIL represents email notifications
	EMAIL Channels = "EMAIL"
	// INAPP_WEB represents in-app web notifications
	INAPP_WEB Channels = "INAPP_WEB"
	// SMS represents SMS notifications
	SMS Channels = "SMS"
	// CALL represents call notifications
	CALL Channels = "CALL"
	// PUSH represents push notifications
	PUSH Channels = "PUSH"
	// WEB_PUSH represents web push notifications
	WEB_PUSH Channels = "WEB_PUSH"
)

// PushProviders represents push notification providers
type PushProviders string

const (
	// FCM represents Firebase Cloud Messaging
	FCM PushProviders = "FCM"
	// APN represents Apple Push Notification service
	APN PushProviders = "APN"
)

// Device contains information about a device for push notifications
type Device struct {
	// AppID is the ID of the application the token is used for
	AppID *string `json:"app_id,omitempty"`
	// AdID is the advertising identifier
	AdID *string `json:"ad_id,omitempty"`
	// DeviceID is the ID of the device the token is associated with
	DeviceID string `json:"device_id"`
	// Platform is the device platform (e.g., android, ios)
	Platform *string `json:"platform,omitempty"`
	// Manufacturer is the device manufacturer
	Manufacturer *string `json:"manufacturer,omitempty"`
	// Model is the device model
	Model *string `json:"model,omitempty"`
}

// PushToken represents a push notification token
type PushToken struct {
	// Type indicates the provider token (APN or FCM)
	Type PushProviders `json:"type"`
	// Token is the full token string
	Token string `json:"token"`
	// Device contains information about the device
	Device Device `json:"device"`
}

// PushSubscription represents a web push subscription
type PushSubscription struct {
	// Endpoint is the endpoint associated with the push subscription
	Endpoint string `json:"endpoint"`
	// Keys contains the subscription keys
	Keys struct {
		// P256dh is the P-256 ECDH public key
		P256dh string `json:"p256dh"`
		// Auth is the authentication secret
		Auth string `json:"auth"`
	} `json:"keys"`
}

// WebPushToken represents a web push token
type WebPushToken struct {
	// Sub is the push subscription
	Sub PushSubscription `json:"sub"`
}

// SlackToken represents Slack OAuth token information
type SlackToken struct {
	AccessToken *string `json:"access_token,omitempty"`
	AppID       *string `json:"app_id,omitempty"`
	AuthedUser  *struct {
		AccessToken  *string `json:"access_token,omitempty"`
		ExpiresIn    *int    `json:"expires_in,omitempty"`
		ID           *string `json:"id,omitempty"`
		RefreshToken *string `json:"refresh_token,omitempty"`
		Scope        *string `json:"scope,omitempty"`
		TokenType    *string `json:"token_type,omitempty"`
	} `json:"authed_user,omitempty"`
	BotUserID  *string `json:"bot_user_id,omitempty"`
	Enterprise *struct {
		ID   *string `json:"id,omitempty"`
		Name *string `json:"name,omitempty"`
	} `json:"enterprise,omitempty"`
	Error           *string `json:"error,omitempty"`
	ExpiresIn       *int    `json:"expires_in,omitempty"`
	IncomingWebhook *struct {
		Channel          *string `json:"channel,omitempty"`
		ChannelID        *string `json:"channel_id,omitempty"`
		ConfigurationURL *string `json:"configuration_url,omitempty"`
		URL              *string `json:"url,omitempty"`
	} `json:"incoming_webhook,omitempty"`
	IsEnterpriseInstall *bool   `json:"is_enterprise_install,omitempty"`
	Needed              *string `json:"needed,omitempty"`
	OK                  *bool   `json:"ok,omitempty"`
	Provided            *string `json:"provided,omitempty"`
	RefreshToken        *string `json:"refresh_token,omitempty"`
	Scope               *string `json:"scope,omitempty"`
	Team                *struct {
		ID   *string `json:"id,omitempty"`
		Name *string `json:"name,omitempty"`
	} `json:"team,omitempty"`
	TokenType *string `json:"token_type,omitempty"`
	Warning   *string `json:"warning,omitempty"`
}

// User represents a user in the NotificationAPI system
type User struct {
	// ID is the user ID in your system (required)
	ID string `json:"id"`
	// Email is required for email notifications, otherwise optional
	Email *string `json:"email,omitempty"`
	// Number is required for SMS/CALL notifications, otherwise optional
	// Valid format: +15005550006. Unformatted US/Canada numbers are also accepted
	Number *string `json:"number,omitempty"`
	// PushTokens are required for mobile push notifications
	PushTokens []PushToken `json:"pushTokens,omitempty"`
	// WebPushTokens are required for web push notifications
	WebPushTokens []WebPushToken `json:"webPushTokens,omitempty"`
	// Timezone is the user's timezone (optional)
	Timezone *string `json:"timezone,omitempty"`
	// LastSeenTime is when the user was last seen (optional)
	LastSeenTime *string `json:"lastSeenTime,omitempty"`
	// SlackChannelName is the user's Slack channel name (optional)
	SlackChannelName *string `json:"slackChannelName,omitempty"`
	// SlackToken is the user's Slack OAuth token (optional)
	SlackToken *SlackToken `json:"slackToken,omitempty"`
	// UpdatedAt is when the user was last updated (optional)
	UpdatedAt *string `json:"updatedAt,omitempty"`
	// CreatedAt is when the user was created (optional)
	CreatedAt *string `json:"createdAt,omitempty"`
}

// EmailAttachment represents an email attachment
type EmailAttachment struct {
	// Filename with file extension for proper display
	Filename string `json:"filename"`
	// URL pointing to the file (must be valid for a few minutes)
	URL string `json:"url"`
}

// EmailOptions contains email-specific options
type EmailOptions struct {
	// ReplyToAddresses for the reply-to field
	ReplyToAddresses []string `json:"replyToAddresses,omitempty"`
	// CCAddresses to be CC'ed on the email
	CCAddresses []string `json:"ccAddresses,omitempty"`
	// BCCAddresses to be BCC'ed on the email
	BCCAddresses []string `json:"bccAddresses,omitempty"`
	// FromName displayed as the "from" field
	FromName *string `json:"fromName,omitempty"`
	// FromAddress displayed as the "from" field
	FromAddress *string `json:"fromAddress,omitempty"`
	// Attachments to include in the email
	Attachments []EmailAttachment `json:"attachments,omitempty"`
}

// APNOptions contains Apple Push Notification options
type APNOptions struct {
	Expiry           *int    `json:"expiry,omitempty"`
	Priority         *int    `json:"priority,omitempty"`
	CollapseID       *string `json:"collapseId,omitempty"`
	ThreadID         *string `json:"threadId,omitempty"`
	Badge            *int    `json:"badge,omitempty"`
	Sound            *string `json:"sound,omitempty"`
	ContentAvailable *bool   `json:"contentAvailable,omitempty"`
}

// AndroidFCMOptions contains Android-specific FCM options
type AndroidFCMOptions struct {
	CollapseKey           *string `json:"collapseKey,omitempty"`
	Priority              *string `json:"priority,omitempty"` // "high" or "normal"
	TTL                   *int    `json:"ttl,omitempty"`
	RestrictedPackageName *string `json:"restrictedPackageName,omitempty"`
}

// FCMOptions contains Firebase Cloud Messaging options
type FCMOptions struct {
	Android *AndroidFCMOptions `json:"android,omitempty"`
}

// NotificationOptions contains various notification options
type NotificationOptions struct {
	// Email-specific options
	Email *EmailOptions `json:"email,omitempty"`
	// APN-specific options
	APN *APNOptions `json:"apn,omitempty"`
	// FCM-specific options
	FCM *FCMOptions `json:"fcm,omitempty"`
}

// ChannelSpecificContent contains channel-specific content
type ChannelEmail struct {
	Subject     string  `json:"subject"`
	HTML        string  `json:"html"`
	PreviewText *string `json:"previewText,omitempty"`
	SenderName  *string `json:"senderName,omitempty"`
	SenderEmail *string `json:"senderEmail,omitempty"`
}

type ChannelInApp struct {
	Title string  `json:"title"`
	URL   *string `json:"url,omitempty"`
	Image *string `json:"image,omitempty"`
}

type ChannelSMS struct {
	Message string `json:"message"`
}

type ChannelCall struct {
	Message string `json:"message"`
}

type ChannelWebPush struct {
	Title   string  `json:"title"`
	Message string  `json:"message"`
	Icon    *string `json:"icon,omitempty"`
	URL     *string `json:"url,omitempty"`
}

type ChannelMobilePush struct {
	Title   string `json:"title"`
	Message string `json:"message"`
}

// SlackBlock represents a Slack block (simplified version)
type SlackBlock interface{}

type ChannelSlack struct {
	Text   string       `json:"text"`
	Blocks []SlackBlock `json:"blocks,omitempty"`
}

// SendRequest represents a request to send a notification
type SendRequest struct {
	// Deprecated: Use Type instead
	NotificationID *string `json:"notificationId,omitempty"`
	// Deprecated: Use To instead
	User *User `json:"user,omitempty"`
	// Deprecated: Use Parameters instead
	MergeTags map[string]interface{} `json:"mergeTags,omitempty"`
	// Deprecated
	Replace map[string]string `json:"replace,omitempty"`

	// Type is the notification type (previously NotificationID)
	Type *string `json:"type,omitempty"`
	// To is the recipient of the notification
	To *User `json:"to,omitempty"`
	// ForceChannels overrides the default channels for the notification
	ForceChannels []Channels `json:"forceChannels,omitempty"`
	// Parameters to be used in the notification template
	Parameters map[string]interface{} `json:"parameters,omitempty"`
	// Deprecated: Use SubNotificationID instead
	SecondaryID *string `json:"secondaryId,omitempty"`
	// TemplateID forces using a specific template
	TemplateID *string `json:"templateId,omitempty"`
	// SubNotificationID specifies subcategories within a notification
	SubNotificationID *string `json:"subNotificationId,omitempty"`
	// Options for modifying notification behavior
	Options *NotificationOptions `json:"options,omitempty"`
	// Schedule is an ISO 8601 datetime string to schedule the notification
	Schedule *string `json:"schedule,omitempty"`

	// Channel-specific options
	Email      *ChannelEmail      `json:"email,omitempty"`
	InApp      *ChannelInApp      `json:"inapp,omitempty"`
	SMS        *ChannelSMS        `json:"sms,omitempty"`
	Call       *ChannelCall       `json:"call,omitempty"`
	WebPush    *ChannelWebPush    `json:"web_push,omitempty"`
	MobilePush *ChannelMobilePush `json:"mobile_push,omitempty"`
	Slack      *ChannelSlack      `json:"slack,omitempty"`
}

// RetractRequest represents a request to retract a notification
type RetractRequest struct {
	// NotificationID is the ID of the notification in NotificationAPI (required)
	NotificationID string `json:"notificationId"`
	// UserID is the ID of the user in your system (required)
	UserID string `json:"userId"`
	// SecondaryID will be deprecated soon
	SecondaryID *string `json:"secondaryId,omitempty"`
	// SubNotificationID specifies subcategories within a notification
	SubNotificationID *string `json:"subNotificationId,omitempty"`
}

// CreateSubNotificationRequest represents a request to create a sub-notification
type CreateSubNotificationRequest struct {
	// NotificationID is the ID of the notification in NotificationAPI (required)
	NotificationID string `json:"notificationId"`
	// Title is the title of the sub-notification (required)
	Title string `json:"title"`
	// SubNotificationID specifies the sub-notification ID (required)
	SubNotificationID string `json:"subNotificationId"`
}

// DeleteSubNotificationRequest represents a request to delete a sub-notification
type DeleteSubNotificationRequest struct {
	// NotificationID is the ID of the notification in NotificationAPI (required)
	NotificationID string `json:"notificationId"`
	// SubNotificationID specifies the sub-notification ID to delete (required)
	SubNotificationID string `json:"subNotificationId"`
}

// SetUserPreferencesRequest represents user notification preferences
type SetUserPreferencesRequest struct {
	// NotificationID is the ID of the notification in NotificationAPI (required)
	NotificationID string `json:"notificationId"`
	// Channel related to the user preferences (optional)
	Channel *string `json:"channel,omitempty"`
	// Delivery method for the notification (optional)
	Delivery *string `json:"delivery,omitempty"` // "off", "instant", "hourly", "daily", "weekly", "monthly"
	// SubNotificationID specifies subcategories within a notification (optional)
	SubNotificationID *string `json:"subNotificationId,omitempty"`
}

// ReplyInfo represents reply information for in-app notifications
type ReplyInfo struct {
	Date    string `json:"date"`
	Message string `json:"message"`
}

// InAppNotificationPatchRequest represents a request to update in-app notifications
type InAppNotificationPatchRequest struct {
	// TrackingIDs to update
	TrackingIDs []string `json:"trackingIds"`
	// Opened timestamp
	Opened *string `json:"opened,omitempty"`
	// Clicked timestamp
	Clicked *string `json:"clicked,omitempty"`
	// Archived timestamp
	Archived *string `json:"archived,omitempty"`
	// Actioned1 timestamp
	Actioned1 *string `json:"actioned1,omitempty"`
	// Actioned2 timestamp
	Actioned2 *string `json:"actioned2,omitempty"`
	// Reply information
	Reply *ReplyInfo `json:"reply,omitempty"`
}

// DateRangeFilter represents a date range filter for log queries
type DateRangeFilter struct {
	// StartTime as Unix timestamp (cannot be less than log retention period)
	StartTime *int64 `json:"startTime,omitempty"`
	// EndTime as Unix timestamp
	EndTime *int64 `json:"endTime,omitempty"`
}

// QueryLogsPostBody represents the body for querying logs
type QueryLogsPostBody struct {
	// DateRangeFilter filters logs by date range
	DateRangeFilter *DateRangeFilter `json:"dateRangeFilter,omitempty"`
	// NotificationFilter filters by specific notification IDs
	NotificationFilter []string `json:"notificationFilter,omitempty"`
	// ChannelFilter filters by specific channels
	ChannelFilter []Channels `json:"channelFilter,omitempty"`
	// UserFilter filters by specific user IDs
	UserFilter []string `json:"userFilter,omitempty"`
	// StatusFilter filters by specific statuses
	StatusFilter []string `json:"statusFilter,omitempty"`
	// TrackingIDs filters by specific tracking IDs
	TrackingIDs []string `json:"trackingIds,omitempty"`
	// RequestFilter filters by specific body request of send request
	RequestFilter []string `json:"requestFilter,omitempty"`
	// EnvIDFilter filters by specific environment IDs
	EnvIDFilter []string `json:"envIdFilter,omitempty"`
	// CustomFilter allows advanced querying (overwrites all other filters)
	CustomFilter *string `json:"customFilter,omitempty"`
}