sentdm 0.44.0 → 0.46.0

data/rbi/sentdm/models/entity_type.rbi

@@ -0,0 +1,23 @@
+# typed: strong
+
+module Sentdm
+  module Models
+    module EntityType
+      extend Sentdm::Internal::Type::Enum
+
+      TaggedSymbol = T.type_alias { T.all(Symbol, Sentdm::EntityType) }
+      OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+      PRIVATE_PROFIT = T.let(:PRIVATE_PROFIT, Sentdm::EntityType::TaggedSymbol)
+      PUBLIC_PROFIT = T.let(:PUBLIC_PROFIT, Sentdm::EntityType::TaggedSymbol)
+      NON_PROFIT = T.let(:NON_PROFIT, Sentdm::EntityType::TaggedSymbol)
+      SOLE_PROPRIETOR =
+        T.let(:SOLE_PROPRIETOR, Sentdm::EntityType::TaggedSymbol)
+      GOVERNMENT = T.let(:GOVERNMENT, Sentdm::EntityType::TaggedSymbol)
+
+      sig { override.returns(T::Array[Sentdm::EntityType::TaggedSymbol]) }
+      def self.values
+      end
+    end
+  end
+end

data/rbi/sentdm/models/inbound_media.rbi

@@ -0,0 +1,76 @@
+# typed: strong
+
+module Sentdm
+  module Models
+    class InboundMedia < Sentdm::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias { T.any(Sentdm::InboundMedia, Sentdm::Internal::AnyHash) }
+
+      # SHA-256 of the file as the carrier declared it, when it declares one. Verify
+      # what you download against this — sent.dm never reads the bytes, so it is the
+      # only integrity signal available.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :hash_sha256
+
+      # Content type as the carrier reported it, for example image/jpeg.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :mime_type
+
+      # Size in bytes as the carrier declared it. Absent when it declared none.
+      sig { returns(T.nilable(Integer)) }
+      attr_accessor :size_bytes
+
+      # Where the carrier hosts the attachment.
+      #
+      # This link expires and is not authenticated. sent.dm relays it rather than
+      # copying the file, so how long it stays fetchable is the carrier's decision and
+      # differs between them — assume days, not months. Anyone holding the URL can fetch
+      # it until it lapses. Copy the file on receipt if you need it to outlive that
+      # window; do not store this URL as a permanent reference.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :url
+
+      # One attachment on an inbound message.
+      sig do
+        params(
+          hash_sha256: T.nilable(String),
+          mime_type: T.nilable(String),
+          size_bytes: T.nilable(Integer),
+          url: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # SHA-256 of the file as the carrier declared it, when it declares one. Verify
+        # what you download against this — sent.dm never reads the bytes, so it is the
+        # only integrity signal available.
+        hash_sha256: nil,
+        # Content type as the carrier reported it, for example image/jpeg.
+        mime_type: nil,
+        # Size in bytes as the carrier declared it. Absent when it declared none.
+        size_bytes: nil,
+        # Where the carrier hosts the attachment.
+        #
+        # This link expires and is not authenticated. sent.dm relays it rather than
+        # copying the file, so how long it stays fetchable is the carrier's decision and
+        # differs between them — assume days, not months. Anyone holding the URL can fetch
+        # it until it lapses. Copy the file on receipt if you need it to outlive that
+        # window; do not store this URL as a permanent reference.
+        url: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            hash_sha256: T.nilable(String),
+            mime_type: T.nilable(String),
+            size_bytes: T.nilable(Integer),
+            url: T.nilable(String)
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/sentdm/models/inbound_message_event_payload.rbi

@@ -40,9 +40,7 @@ module Sentdm
       # /v3/messages/{id} returns the same stored link, not a fresh one, so once it
       # lapses the entry remains with whatever the carrier declared about the file but
       # the file is no longer reachable.
-      sig do
-        returns(T.nilable(T::Array[Sentdm::InboundMessageEventPayload::Media]))
-      end
+      sig { returns(T.nilable(T::Array[Sentdm::InboundMedia])) }
       attr_accessor :media
 
       # The inbound message.
@@ -93,10 +91,7 @@ module Sentdm
           received_at: String,
           account_id: String,
           channel: String,
-          media:
-            T.nilable(
-              T::Array[Sentdm::InboundMessageEventPayload::Media::OrHash]
-            ),
+          media: T.nilable(T::Array[Sentdm::InboundMedia::OrHash]),
           message_id: String,
           outbound_number: String,
           referral: T.nilable(T.anything),
@@ -155,8 +150,7 @@ module Sentdm
             received_at: String,
             account_id: String,
             channel: String,
-            media:
-              T.nilable(T::Array[Sentdm::InboundMessageEventPayload::Media]),
+            media: T.nilable(T::Array[Sentdm::InboundMedia]),
             message_id: String,
             outbound_number: String,
             referral: T.nilable(T.anything),
@@ -167,82 +161,6 @@ module Sentdm
       end
       def to_hash
       end
-
-      class Media < Sentdm::Internal::Type::BaseModel
-        OrHash =
-          T.type_alias do
-            T.any(
-              Sentdm::InboundMessageEventPayload::Media,
-              Sentdm::Internal::AnyHash
-            )
-          end
-
-        # SHA-256 of the file as the carrier declared it, when it declares one. Verify
-        # what you download against this — sent.dm never reads the bytes, so it is the
-        # only integrity signal available.
-        sig { returns(T.nilable(String)) }
-        attr_accessor :hash_sha256
-
-        # Content type as the carrier reported it, for example image/jpeg.
-        sig { returns(T.nilable(String)) }
-        attr_accessor :mime_type
-
-        # Size in bytes as the carrier declared it. Absent when it declared none.
-        sig { returns(T.nilable(Integer)) }
-        attr_accessor :size_bytes
-
-        # Where the carrier hosts the attachment.
-        #
-        # This link expires and is not authenticated. sent.dm relays it rather than
-        # copying the file, so how long it stays fetchable is the carrier's decision and
-        # differs between them — assume days, not months. Anyone holding the URL can fetch
-        # it until it lapses. Copy the file on receipt if you need it to outlive that
-        # window; do not store this URL as a permanent reference.
-        sig { returns(T.nilable(String)) }
-        attr_accessor :url
-
-        # One attachment on an inbound message.
-        sig do
-          params(
-            hash_sha256: T.nilable(String),
-            mime_type: T.nilable(String),
-            size_bytes: T.nilable(Integer),
-            url: T.nilable(String)
-          ).returns(T.attached_class)
-        end
-        def self.new(
-          # SHA-256 of the file as the carrier declared it, when it declares one. Verify
-          # what you download against this — sent.dm never reads the bytes, so it is the
-          # only integrity signal available.
-          hash_sha256: nil,
-          # Content type as the carrier reported it, for example image/jpeg.
-          mime_type: nil,
-          # Size in bytes as the carrier declared it. Absent when it declared none.
-          size_bytes: nil,
-          # Where the carrier hosts the attachment.
-          #
-          # This link expires and is not authenticated. sent.dm relays it rather than
-          # copying the file, so how long it stays fetchable is the carrier's decision and
-          # differs between them — assume days, not months. Anyone holding the URL can fetch
-          # it until it lapses. Copy the file on receipt if you need it to outlive that
-          # window; do not store this URL as a permanent reference.
-          url: nil
-        )
-        end
-
-        sig do
-          override.returns(
-            {
-              hash_sha256: T.nilable(String),
-              mime_type: T.nilable(String),
-              size_bytes: T.nilable(Integer),
-              url: T.nilable(String)
-            }
-          )
-        end
-        def to_hash
-        end
-      end
     end
   end
 end

data/rbi/sentdm/models/link_event.rbi

@@ -0,0 +1,128 @@
+# typed: strong
+
+module Sentdm
+  module Models
+    class LinkEvent < Sentdm::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias { T.any(Sentdm::LinkEvent, Sentdm::Internal::AnyHash) }
+
+      # The specific event within the family, for example message.delivered,
+      # message.received or contact.opt_out. Absent on events that have no subtype, so
+      # treat it as optional.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :event
+
+      # The event family, for example message, templates or contact. Route on this
+      # first, then on event for the specific change.
+      sig { returns(T.nilable(String)) }
+      attr_reader :field
+
+      sig { params(field: String).void }
+      attr_writer :field
+
+      # Body of a link event: something happened to a tracked link Sent published on the
+      # customer's behalf. A link points either at a URL the customer supplied or at a
+      # file Sent hosts for them; LinkKind says which. Delivered when an eligible
+      # request is served, or when a published link reaches the end of its life.
+      #
+      # A click is a request, not a read receipt. link.clicked means the redirect was
+      # served; link.downloaded means bytes went out. Neither proves a person saw
+      # anything — messaging providers and link scanners fetch URLs on their own, which
+      # is what TrafficClass exists to tell apart. Filter on it before reporting a
+      # click-through rate; treat likely_human as a hint, never as delivery
+      # confirmation.
+      #
+      # RecordId identifies the link; the X-Webhook-Event-ID header identifies the
+      # delivery. One link is hit many times, so those are the two keys a subscriber
+      # needs: group by the first, deduplicate on the second — exactly as on every other
+      # family. The payload carries no event identifier of its own, for the same reason
+      # none of the others do.
+      #
+      # Nothing here identifies the visitor. No IP address and no visitor token crosses
+      # this boundary. Country, Device and Browser are coarse buckets derived at the
+      # edge and are absent whenever the request did not supply enough to derive them.
+      sig { returns(T.nilable(Sentdm::LinkEventPayload)) }
+      attr_reader :payload
+
+      sig { params(payload: T.nilable(Sentdm::LinkEventPayload::OrHash)).void }
+      attr_writer :payload
+
+      # The event-specific body.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :request_id
+
+      # When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
+      # time, not the time the underlying change happened. Use the timestamp inside the
+      # payload for the latter.
+      sig { returns(T.nilable(String)) }
+      attr_reader :timestamp
+
+      sig { params(timestamp: String).void }
+      attr_writer :timestamp
+
+      # The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares
+      # this shape and varies only in Payload.
+      sig do
+        params(
+          event: T.nilable(String),
+          field: String,
+          payload: T.nilable(Sentdm::LinkEventPayload::OrHash),
+          request_id: T.nilable(String),
+          timestamp: String
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # The specific event within the family, for example message.delivered,
+        # message.received or contact.opt_out. Absent on events that have no subtype, so
+        # treat it as optional.
+        event: nil,
+        # The event family, for example message, templates or contact. Route on this
+        # first, then on event for the specific change.
+        field: nil,
+        # Body of a link event: something happened to a tracked link Sent published on the
+        # customer's behalf. A link points either at a URL the customer supplied or at a
+        # file Sent hosts for them; LinkKind says which. Delivered when an eligible
+        # request is served, or when a published link reaches the end of its life.
+        #
+        # A click is a request, not a read receipt. link.clicked means the redirect was
+        # served; link.downloaded means bytes went out. Neither proves a person saw
+        # anything — messaging providers and link scanners fetch URLs on their own, which
+        # is what TrafficClass exists to tell apart. Filter on it before reporting a
+        # click-through rate; treat likely_human as a hint, never as delivery
+        # confirmation.
+        #
+        # RecordId identifies the link; the X-Webhook-Event-ID header identifies the
+        # delivery. One link is hit many times, so those are the two keys a subscriber
+        # needs: group by the first, deduplicate on the second — exactly as on every other
+        # family. The payload carries no event identifier of its own, for the same reason
+        # none of the others do.
+        #
+        # Nothing here identifies the visitor. No IP address and no visitor token crosses
+        # this boundary. Country, Device and Browser are coarse buckets derived at the
+        # edge and are absent whenever the request did not supply enough to derive them.
+        payload: nil,
+        # The event-specific body.
+        request_id: nil,
+        # When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
+        # time, not the time the underlying change happened. Use the timestamp inside the
+        # payload for the latter.
+        timestamp: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            event: T.nilable(String),
+            field: String,
+            payload: T.nilable(Sentdm::LinkEventPayload),
+            request_id: T.nilable(String),
+            timestamp: String
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/sentdm/models/link_event_payload.rbi

@@ -0,0 +1,279 @@
+# typed: strong
+
+module Sentdm
+  module Models
+    class LinkEventPayload < Sentdm::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Sentdm::LinkEventPayload, Sentdm::Internal::AnyHash)
+        end
+
+      # The link's public identifier — the eight-character code in the short URL, for
+      # example A78B2BU0. Unique across both kinds, and never reused, so it is the
+      # stable key to group one link's events by.
+      sig { returns(String) }
+      attr_accessor :record_id
+
+      # Where the request appeared to come from, as an ISO 3166-1 alpha-2 code. Named
+      # separately from the country on a channel event, which is a destination market
+      # the customer registered for — this one is a property of a single visitor and is
+      # absent when the edge could not resolve it.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :access_country
+
+      # How the request was served, when the edge recorded it. Free text describing the
+      # outcome — show it to a human rather than branching on it.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :access_outcome
+
+      # The requesting browser family, for example chrome or safari, or unknown. Derived
+      # from the user agent.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :browser
+
+      # How many bytes were served, for a file access. A ranged request reports the
+      # bytes in that range, not the size of the file, so several accesses of one file
+      # can each report a part.
+      sig { returns(T.nilable(Integer)) }
+      attr_accessor :bytes_served
+
+      # The channel the message carrying this link went out on: sms, whatsapp, or rcs.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :channel
+
+      # The organization the link belongs to. Always the parent account, never a sender
+      # profile — read SenderProfileId for that.
+      #
+      # This family publishes the owner as an explicit pair rather than the single
+      # account_id the other families use. The pair says which organization and which
+      # profile without the subscriber deriving either, which is the trade: one more key
+      # against not having to know that account_id silently becomes the profile when one
+      # exists.
+      sig { returns(T.nilable(String)) }
+      attr_reader :customer_id
+
+      sig { params(customer_id: String).void }
+      attr_writer :customer_id
+
+      # The requesting device class: mobile, tablet, desktop or unknown. Derived from
+      # the user agent.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :device
+
+      # What the link points at: url for a destination the customer supplied, file for
+      # media Sent hosts. Always present, and implied by the event — link.clicked is
+      # always url and link.downloaded always file — but published as its own field so a
+      # subscriber can branch on the kind without parsing the event name, the same
+      # separation the channel family keeps between its event and its status.
+      sig { returns(T.nilable(String)) }
+      attr_reader :link_kind
+
+      sig { params(link_kind: String).void }
+      attr_writer :link_kind
+
+      # The message the link was published in.
+      #
+      # The event can arrive before the message is readable through GET /v3/messages: a
+      # provider may fetch a link within milliseconds of the send, and nothing here
+      # waits for the message row. Retry the read rather than treating an unknown id as
+      # an error.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :message_id
+
+      # When the access or lifecycle change actually happened, in UTC
+      # (yyyy-MM-ddTHH:mm:ssZ). The envelope's timestamp is when Sent emitted the event;
+      # this is when the thing occurred, and the two differ by the ingest delay.
+      sig { returns(T.nilable(String)) }
+      attr_reader :occurred_at
+
+      sig { params(occurred_at: String).void }
+      attr_writer :occurred_at
+
+      # The caller-supplied label tying this link back to a position in the message, for
+      # example body:0 for the first link in the body. Present when the link was created
+      # with one.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :reference_key
+
+      # The host of the page that linked here, when the request supplied one. The host
+      # only — never a full referring URL.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :referrer_host
+
+      # The HTTP method of the request that was served, for an access event. Omitted on
+      # link.expired and link.revoked, which describe no request.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :request_method
+
+      # The sender profile that owns the link, or null when the organization owns it
+      # directly. Always on the wire so a handler reads one shape rather than branching
+      # on whether the key arrived.
+      #
+      # sender_profile_id, not profile_id: the API already publishes
+      # messaging_profile_id and sending_phone_number_profile_id for provider-side
+      # profiles, which are a different thing entirely. The unqualified name would read
+      # as one of those.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :sender_profile_id
+
+      # The HTTP status Sent answered the request with: 302 for a link, 200 or 206 for a
+      # file. Omitted on lifecycle events.
+      sig { returns(T.nilable(Integer)) }
+      attr_accessor :status_code
+
+      # A coarse guess at what made the request: likely_human, provider (a messaging
+      # platform prefetching the link), bot, or unknown. Derived from the user agent, so
+      # it is a hint for filtering noise rather than a fact to bill or report on.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :traffic_class
+
+      # Body of a link event: something happened to a tracked link Sent published on the
+      # customer's behalf. A link points either at a URL the customer supplied or at a
+      # file Sent hosts for them; LinkKind says which. Delivered when an eligible
+      # request is served, or when a published link reaches the end of its life.
+      #
+      # A click is a request, not a read receipt. link.clicked means the redirect was
+      # served; link.downloaded means bytes went out. Neither proves a person saw
+      # anything — messaging providers and link scanners fetch URLs on their own, which
+      # is what TrafficClass exists to tell apart. Filter on it before reporting a
+      # click-through rate; treat likely_human as a hint, never as delivery
+      # confirmation.
+      #
+      # RecordId identifies the link; the X-Webhook-Event-ID header identifies the
+      # delivery. One link is hit many times, so those are the two keys a subscriber
+      # needs: group by the first, deduplicate on the second — exactly as on every other
+      # family. The payload carries no event identifier of its own, for the same reason
+      # none of the others do.
+      #
+      # Nothing here identifies the visitor. No IP address and no visitor token crosses
+      # this boundary. Country, Device and Browser are coarse buckets derived at the
+      # edge and are absent whenever the request did not supply enough to derive them.
+      sig do
+        params(
+          record_id: String,
+          access_country: T.nilable(String),
+          access_outcome: T.nilable(String),
+          browser: T.nilable(String),
+          bytes_served: T.nilable(Integer),
+          channel: T.nilable(String),
+          customer_id: String,
+          device: T.nilable(String),
+          link_kind: String,
+          message_id: T.nilable(String),
+          occurred_at: String,
+          reference_key: T.nilable(String),
+          referrer_host: T.nilable(String),
+          request_method: T.nilable(String),
+          sender_profile_id: T.nilable(String),
+          status_code: T.nilable(Integer),
+          traffic_class: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # The link's public identifier — the eight-character code in the short URL, for
+        # example A78B2BU0. Unique across both kinds, and never reused, so it is the
+        # stable key to group one link's events by.
+        record_id:,
+        # Where the request appeared to come from, as an ISO 3166-1 alpha-2 code. Named
+        # separately from the country on a channel event, which is a destination market
+        # the customer registered for — this one is a property of a single visitor and is
+        # absent when the edge could not resolve it.
+        access_country: nil,
+        # How the request was served, when the edge recorded it. Free text describing the
+        # outcome — show it to a human rather than branching on it.
+        access_outcome: nil,
+        # The requesting browser family, for example chrome or safari, or unknown. Derived
+        # from the user agent.
+        browser: nil,
+        # How many bytes were served, for a file access. A ranged request reports the
+        # bytes in that range, not the size of the file, so several accesses of one file
+        # can each report a part.
+        bytes_served: nil,
+        # The channel the message carrying this link went out on: sms, whatsapp, or rcs.
+        channel: nil,
+        # The organization the link belongs to. Always the parent account, never a sender
+        # profile — read SenderProfileId for that.
+        #
+        # This family publishes the owner as an explicit pair rather than the single
+        # account_id the other families use. The pair says which organization and which
+        # profile without the subscriber deriving either, which is the trade: one more key
+        # against not having to know that account_id silently becomes the profile when one
+        # exists.
+        customer_id: nil,
+        # The requesting device class: mobile, tablet, desktop or unknown. Derived from
+        # the user agent.
+        device: nil,
+        # What the link points at: url for a destination the customer supplied, file for
+        # media Sent hosts. Always present, and implied by the event — link.clicked is
+        # always url and link.downloaded always file — but published as its own field so a
+        # subscriber can branch on the kind without parsing the event name, the same
+        # separation the channel family keeps between its event and its status.
+        link_kind: nil,
+        # The message the link was published in.
+        #
+        # The event can arrive before the message is readable through GET /v3/messages: a
+        # provider may fetch a link within milliseconds of the send, and nothing here
+        # waits for the message row. Retry the read rather than treating an unknown id as
+        # an error.
+        message_id: nil,
+        # When the access or lifecycle change actually happened, in UTC
+        # (yyyy-MM-ddTHH:mm:ssZ). The envelope's timestamp is when Sent emitted the event;
+        # this is when the thing occurred, and the two differ by the ingest delay.
+        occurred_at: nil,
+        # The caller-supplied label tying this link back to a position in the message, for
+        # example body:0 for the first link in the body. Present when the link was created
+        # with one.
+        reference_key: nil,
+        # The host of the page that linked here, when the request supplied one. The host
+        # only — never a full referring URL.
+        referrer_host: nil,
+        # The HTTP method of the request that was served, for an access event. Omitted on
+        # link.expired and link.revoked, which describe no request.
+        request_method: nil,
+        # The sender profile that owns the link, or null when the organization owns it
+        # directly. Always on the wire so a handler reads one shape rather than branching
+        # on whether the key arrived.
+        #
+        # sender_profile_id, not profile_id: the API already publishes
+        # messaging_profile_id and sending_phone_number_profile_id for provider-side
+        # profiles, which are a different thing entirely. The unqualified name would read
+        # as one of those.
+        sender_profile_id: nil,
+        # The HTTP status Sent answered the request with: 302 for a link, 200 or 206 for a
+        # file. Omitted on lifecycle events.
+        status_code: nil,
+        # A coarse guess at what made the request: likely_human, provider (a messaging
+        # platform prefetching the link), bot, or unknown. Derived from the user agent, so
+        # it is a hint for filtering noise rather than a fact to bill or report on.
+        traffic_class: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            record_id: String,
+            access_country: T.nilable(String),
+            access_outcome: T.nilable(String),
+            browser: T.nilable(String),
+            bytes_served: T.nilable(Integer),
+            channel: T.nilable(String),
+            customer_id: String,
+            device: T.nilable(String),
+            link_kind: String,
+            message_id: T.nilable(String),
+            occurred_at: String,
+            reference_key: T.nilable(String),
+            referrer_host: T.nilable(String),
+            request_method: T.nilable(String),
+            sender_profile_id: T.nilable(String),
+            status_code: T.nilable(Integer),
+            traffic_class: T.nilable(String)
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end