__package__.yml

# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json

imports:
  ids: ids.yml
  user: user.yml

service:
  display-name: Event Service
  auth: true
  base-path: /v1/apps
  headers:
    Idempotency-Key:
      type: optional<string>
      docs: |
        The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. 
        This is useful when an API call is disrupted in transit and you do not receive a response.
        For example, if a request to send event does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one event is sent.
        An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. 
        How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. 
        Idempotency keys can be up to 255 characters long.
  endpoints:
    send:
      docs: This endpoint allows you to send messages
      method: POST
      path: /{app_id}/events/send
      path-parameters:
        app_id:
          type: ids.AppId
          docs: The `id` of the app
      request:
        name: SendEventRequest
        body:
          properties:
            event:
              type: string
              docs: The name of the event
            data: map<string, unknown>
            user:
              type: optional<User>
            scheduleAt:
              type: optional<long>
              docs: |
                Time to send message expressed as UTC milliseconds. 
                If not present, message will be sent immediately.
            override:
              type: optional<EventOverride>
      response: SendEventResponse
      errors:
        - EventNotFoundError
      examples:
        # success
        - path-parameters:
            app_id: my_app_id
          request:
            event: sample_event_1
            data:
              name: name
              date: 01 December 2022
            user:
              mobile: "+919876543210"
              email: x@ravenapp.dev
              whatsapp_mobile: "+919876543210"
          response:
            body:
              id: 1d1ed73c-96e6-4aa3-abc2-2e9a926f773a
              success: true
        # error
        - path-parameters:
            app_id: my_app_id
          request:
            event: sample_event_1
            data:
              name: name
              date: 01 December 2022
            user:
              mobile: "+919876543210"
              email: x@ravenapp.dev
              whatsapp_mobile: "+919876543210"
          response:
            error: EventNotFoundError
            body:
              success: false
              error: event not found

    sendBulk:
      method: POST
      path: /{app_id}/events/bulk_send
      path-parameters:
        app_id: ids.AppId
      request:
        name: BulkSendEventRequest
        body:
          properties:
            event: string
            batch:
              type: list<BatchEvent>
              docs: List of events
      response: SendEventResponse
      examples:
        - path-parameters:
            app_id: my-app-id
          request:
            event: sample_event_1
            batch:
              - user:
                  mobile: "+919876543210"
                  email: x@ravenapp.dev
                  whatsapp_mobile: "+919876543210"
                data:
                  name: John Doe
                  date: 01 December 2022
              - user:
                  mobile: "+919876543210"
                  email: x@ravenapp.dev
                  whatsapp_mobile: "+919876543210"
                data:
                  name: John Doe
                  date: 01 December 2022
          response:
            body:
              id: 1d1ed73c-96e6-4aa3-abc2-2e9a926f773a
              success: true

types:
  User:
    properties:
      user_id:
        type: optional<ids.UserId>
        docs: |
          userId to send the notifications to. 
          This is  your own user identifier which you have used to [create user on Raven](https://docs.raven.dev/api-reference/create-user)
      email:
        type: optional<string>
      mobile:
        type: optional<string>
        docs: mobile with country code prefix (e.g +91)
      whatsapp_mobile:
        type: optional<string>
        docs: |
          mobile with country code prefix (e.g. +91).
          if empty, `mobile` is considered for whatsapp
      onesignal_external_id:
        type: optional<string>
        docs: |
          [OneSignal external user IDs](https://documentation.onesignal.com/docs/external-user-ids)
      onesignal_player_ids:
        type: optional<list<string>>
      fcm_tokens:
        type: optional<list<string>>
        docs: List of fcm tokens.  eg. ["<fcmtoken1", "<fcmtoken2>"]
      ios_tokens:
        type: optional<list<string>>
      slack:
        type: optional<user.SlackProfile>
      telegram:
        type: optional<user.TelegramProfile>
      fcm_topic:
        type: optional<string>
      fcm_device_group:
        type: optional<string>

  EventOverride:
    properties:
      email: optional<EmailOverride>
      sms: optional<SmsOverride>
      whatsapp: optional<WhatsappOverride>
      push: optional<PushOverride>
      webhook: optional<WebhookOverride>
      voice: optional<VoiceOverride>
      slack: optional<SlackOverride>
      in_app: optional<InAppOverride>
      telegram: optional<TelegramOverride>
      providers: map<string, ProviderOverride>

  ChannelOverride:
    properties:
      schedule_at: long

  EmailRecipient:
    properties:
      name: string
      address: string

  Attachment:
    properties:
      file_name: string
      content: string
      url: string

  EmailMessage:
    properties:
      text: string
      html_body: string
      subject: string

  EmailOverride:
    extends: ChannelOverride
    properties:
      from: EmailRecipient
      cc: list<EmailRecipient>
      bcc: list<EmailRecipient>
      attachments: list<Attachment>
      message: EmailMessage

  SmsMessage:
    properties:
      text: string

  SmsOverride:
    extends: ChannelOverride
    properties:
      sender: string
      message: SmsMessage

  WhatsappOverride:
    extends: ChannelOverride
    properties:
      message: SmsMessage

  PushOverride:
    extends: ChannelOverride

  WebhookOverride:
    extends: ChannelOverride

  VoiceOverride:
    extends: ChannelOverride

  SlackMessage:
    properties:
      text: string
      blocks: unknown

  SlackOverride:
    extends: ChannelOverride
    properties:
      message: SlackMessage

  InAppOverride:
    extends: ChannelOverride

  TelegramOverride:
    extends: ChannelOverride

  Param:
    properties:
      name: string
      value: string

  ProviderOverride:
    properties:
      payload: map<string, unknown>
      form_params: list<Param>
      query_params: list<Param>
      path_params: list<Param>
      headers: list<Param>

  SendEventResponse:
    properties:
      id: ids.RequestId
      success: boolean

  BatchEvent:
    properties:
      data:
        type: map<string, unknown>
        docs: |
          {
          "param1" : "<value1>",
          "param2" : "<value2>",
          "param3" : object/array"
          }
      user:
        type: optional<User>
      override:
        type: optional<EventOverride>

  EventNotFoundErrorBody:
    properties:
      success: boolean
      error: string

errors:
  EventNotFoundError:
    status-code: 404
    type: EventNotFoundErrorBody