fopost 0.1.0 → 0.3.0

data/lib/fopost/resources/whatsapp.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module Fopost
+  module Resources
+    # `client.whatsapp` — a WhatsApp Business connection.
+    #
+    # The platform owns templates, flows, the profile and the commerce settings,
+    # so every method here is a live read or write against the customer's own
+    # WhatsApp Business Account. All of it answers 503 until WhatsApp is set up.
+    class Whatsapp < Base
+      # ─── Profile ─────────────────────────────────────────────────
+
+      def profile(account_id)
+        WhatsappProfile.new(unwrap(http.get("/accounts/#{account_id}/whatsapp/profile")))
+      end
+
+      def update_profile(account_id, about: UNSET, address: UNSET, description: UNSET,
+                         vertical: UNSET, websites: UNSET, profile_picture_media_id: UNSET)
+        body = compact_unset(
+          'about' => about,
+          'address' => address,
+          'description' => description,
+          'vertical' => vertical,
+          'websites' => websites,
+          'profile_picture_media_id' => profile_picture_media_id
+        )
+        WhatsappProfile.new(unwrap(http.request(:patch, "/accounts/#{account_id}/whatsapp/profile", json: body)))
+      end
+
+      # A review, not a write: the number keeps its old name until it passes.
+      def request_display_name(account_id, display_name)
+        body = { 'display_name' => display_name }
+        as_hash(unwrap(http.post("/accounts/#{account_id}/whatsapp/profile/display-name", body)))
+      end
+
+      def set_username(account_id, username)
+        body = { 'username' => username }
+        WhatsappProfile.new(unwrap(http.put("/accounts/#{account_id}/whatsapp/profile/username", body)))
+      end
+
+      # ─── Templates ───────────────────────────────────────────────
+
+      def templates(account_id, after: nil)
+        params = compact_nil('after' => after)
+        parse_list(WhatsappTemplate, unwrap(http.get("/accounts/#{account_id}/whatsapp/templates", params)))
+      end
+
+      # The platform's pre-written templates, for adapting instead of drafting.
+      def template_library(account_id, search: nil)
+        params = compact_nil('search' => search)
+        body = unwrap(http.get("/accounts/#{account_id}/whatsapp/templates/library", params))
+        body.is_a?(Array) ? body : []
+      end
+
+      def template(account_id, template_id)
+        WhatsappTemplate.new(unwrap(http.get("/accounts/#{account_id}/whatsapp/templates/#{template_id}")))
+      end
+
+      # Files a template for review; the result carries the status it was given.
+      def create_template(account_id, name:, language:, category:, components:,
+                          allow_category_change: nil)
+        body = compact_nil(
+          'name' => name,
+          'language' => language,
+          'category' => category,
+          'components' => components.map { |c| c.transform_keys(&:to_s) },
+          'allow_category_change' => allow_category_change
+        )
+        WhatsappTemplate.new(unwrap(http.post("/accounts/#{account_id}/whatsapp/templates", body)))
+      end
+
+      def import_template(account_id, library_template_name:, name:, language:, category:,
+                          library_template_button_inputs: nil)
+        body = compact_nil(
+          'library_template_name' => library_template_name,
+          'name' => name,
+          'language' => language,
+          'category' => category,
+          'library_template_button_inputs' => library_template_button_inputs
+        )
+        WhatsappTemplate.new(unwrap(http.post("/accounts/#{account_id}/whatsapp/templates/import", body)))
+      end
+
+      def update_template(account_id, template_id, category: nil, components: nil)
+        body = compact_nil('category' => category, 'components' => components)
+        path = "/accounts/#{account_id}/whatsapp/templates/#{template_id}"
+        WhatsappTemplate.new(unwrap(http.request(:patch, path, json: body)))
+      end
+
+      # The name is required: it is what the platform deletes by.
+      def delete_template(account_id, template_id, name:)
+        query = URI.encode_www_form('name' => name)
+        as_hash(unwrap(http.delete("/accounts/#{account_id}/whatsapp/templates/#{template_id}?#{query}")))
+      end
+
+      # ─── Groups ──────────────────────────────────────────────────
+
+      def groups(account_id)
+        parse_list(WhatsappGroup, unwrap(http.get("/accounts/#{account_id}/whatsapp/groups")))
+      end
+
+      # Participation is invite-only: send the invite link, there is no add.
+      def create_group(account_id, subject:, description: nil)
+        body = compact_nil('subject' => subject, 'description' => description)
+        WhatsappGroup.new(unwrap(http.post("/accounts/#{account_id}/whatsapp/groups", body)))
+      end
+
+      def group(account_id, group_id)
+        WhatsappGroup.new(unwrap(http.get("/accounts/#{account_id}/whatsapp/groups/#{group_id}")))
+      end
+
+      def update_group(account_id, group_id, subject: nil, description: nil)
+        body = compact_nil('subject' => subject, 'description' => description)
+        path = "/accounts/#{account_id}/whatsapp/groups/#{group_id}"
+        WhatsappGroup.new(unwrap(http.request(:patch, path, json: body)))
+      end
+
+      def delete_group(account_id, group_id)
+        as_hash(unwrap(http.delete("/accounts/#{account_id}/whatsapp/groups/#{group_id}")))
+      end
+
+      def group_invite_link(account_id, group_id)
+        body = as_hash(unwrap(http.get("/accounts/#{account_id}/whatsapp/groups/#{group_id}/invite-link")))
+        body['inviteLink']
+      end
+
+      # Issues a new link and invalidates the old one.
+      def reset_group_invite_link(account_id, group_id)
+        body = as_hash(unwrap(http.post("/accounts/#{account_id}/whatsapp/groups/#{group_id}/invite-link")))
+        body['inviteLink']
+      end
+
+      def remove_group_participants(account_id, group_id, users)
+        path = "/accounts/#{account_id}/whatsapp/groups/#{group_id}/participants"
+        as_hash(unwrap(http.delete(path, { 'users' => users.to_a })))
+      end
+
+      # ─── Blocking ────────────────────────────────────────────────
+
+      def blocked(account_id, after: nil)
+        params = compact_nil('after' => after)
+        body = unwrap(http.get("/accounts/#{account_id}/whatsapp/block", params))
+        body.is_a?(Array) ? body : []
+      end
+
+      def block_users(account_id, users)
+        body = { 'users' => users.to_a }
+        WhatsappBlockResult.new(unwrap(http.post("/accounts/#{account_id}/whatsapp/block", body)))
+      end
+
+      def unblock_users(account_id, users)
+        body = { 'users' => users.to_a }
+        WhatsappBlockResult.new(unwrap(http.delete("/accounts/#{account_id}/whatsapp/block", body)))
+      end
+
+      # ─── Commerce ────────────────────────────────────────────────
+
+      def commerce_settings(account_id)
+        WhatsappCommerceSettings.new(unwrap(http.get("/accounts/#{account_id}/whatsapp/commerce")))
+      end
+
+      def update_commerce_settings(account_id, cart_enabled: nil, catalog_visible: nil)
+        body = compact_nil('is_cart_enabled' => cart_enabled, 'is_catalog_visible' => catalog_visible)
+        path = "/accounts/#{account_id}/whatsapp/commerce"
+        WhatsappCommerceSettings.new(unwrap(http.request(:patch, path, json: body)))
+      end
+
+      def link_catalog(account_id, catalog_id)
+        body = { 'catalog_id' => catalog_id }
+        path = "/accounts/#{account_id}/whatsapp/commerce/catalog"
+        WhatsappCommerceSettings.new(unwrap(http.post(path, body)))
+      end
+
+      # ─── Flows ───────────────────────────────────────────────────
+
+      def flows(account_id)
+        parse_list(WhatsappFlow, unwrap(http.get("/accounts/#{account_id}/whatsapp/flows")))
+      end
+
+      def flow(account_id, flow_id)
+        WhatsappFlow.new(unwrap(http.get("/accounts/#{account_id}/whatsapp/flows/#{flow_id}")))
+      end
+
+      def create_flow(account_id, name:, categories:, endpoint_uri: nil, clone_flow_id: nil)
+        body = compact_nil(
+          'name' => name,
+          'categories' => categories.to_a,
+          'endpoint_uri' => endpoint_uri,
+          'clone_flow_id' => clone_flow_id
+        )
+        WhatsappFlow.new(unwrap(http.post("/accounts/#{account_id}/whatsapp/flows", body)))
+      end
+
+      def update_flow(account_id, flow_id, name: nil, categories: nil, endpoint_uri: nil)
+        body = compact_nil('name' => name, 'categories' => categories, 'endpoint_uri' => endpoint_uri)
+        path = "/accounts/#{account_id}/whatsapp/flows/#{flow_id}"
+        WhatsappFlow.new(unwrap(http.request(:patch, path, json: body)))
+      end
+
+      # Drafts only; a published flow is deprecated instead.
+      def delete_flow(account_id, flow_id)
+        as_hash(unwrap(http.delete("/accounts/#{account_id}/whatsapp/flows/#{flow_id}")))
+      end
+
+      # The platform answers with its validation errors rather than refusing.
+      def upload_flow_json(account_id, flow_id, flow_json)
+        body = { 'flow_json' => flow_json }
+        path = "/accounts/#{account_id}/whatsapp/flows/#{flow_id}/json"
+        WhatsappFlowJsonResult.new(unwrap(http.put(path, body)))
+      end
+
+      def publish_flow(account_id, flow_id)
+        WhatsappFlow.new(unwrap(http.post("/accounts/#{account_id}/whatsapp/flows/#{flow_id}/publish")))
+      end
+
+      def deprecate_flow(account_id, flow_id)
+        WhatsappFlow.new(unwrap(http.post("/accounts/#{account_id}/whatsapp/flows/#{flow_id}/deprecate")))
+      end
+
+      def flow_responses(account_id)
+        path = "/accounts/#{account_id}/whatsapp/flows/responses"
+        parse_list(WhatsappFlowResponse, unwrap(http.get(path)))
+      end
+
+      def encryption_key_status(account_id)
+        path = "/accounts/#{account_id}/whatsapp/flows/encryption-key"
+        WhatsappEncryptionKeyStatus.new(unwrap(http.get(path)))
+      end
+
+      # The public half only; the private half stays with the customer.
+      def set_encryption_key(account_id, business_public_key)
+        body = { 'business_public_key' => business_public_key }
+        path = "/accounts/#{account_id}/whatsapp/flows/encryption-key"
+        WhatsappEncryptionKeyStatus.new(unwrap(http.put(path, body)))
+      end
+
+      # ─── Account state and sandbox ───────────────────────────────
+
+      def account_events(account_id)
+        as_hash(unwrap(http.get("/accounts/#{account_id}/whatsapp/events")))
+      end
+
+      def sandbox_sessions(workspace_id:)
+        params = { 'workspaceId' => workspace_id }
+        parse_list(WhatsappSandboxSession, unwrap(http.get('/whatsapp/sandbox/sessions', params)))
+      end
+
+      # Sends a template from the platform-owned test number; needs the publish scope.
+      def create_sandbox_session(workspace_id:, phone_number:)
+        body = { 'workspaceId' => workspace_id, 'phoneNumber' => phone_number }
+        WhatsappSandboxSession.new(unwrap(http.post('/whatsapp/sandbox/sessions', body)))
+      end
+    end
+  end
+end

data/lib/fopost/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fopost
-  VERSION = '0.1.0'
+  VERSION = '0.3.0'
 end

data/lib/fopost/webhooks.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'openssl'
+require 'time'
+
+require 'fopost/models'
+
+module Fopost
+  # Raised when a webhook delivery cannot be trusted.
+  class WebhookSignatureError < StandardError; end
+
+  # Verifies the signature FoPost puts on every outbound webhook, including
+  # the website target of the blog.
+  #
+  #   event = Fopost::Webhooks.verify(request.raw_post, request.headers, secret)
+  #   event.article.title if event.event == 'article.published'
+  #
+  # Verify the raw request bytes, never re-serialised JSON: key order and
+  # whitespace change the bytes and the signature no longer matches.
+  module Webhooks
+    SIGNATURE_HEADER = 'x-fopost-signature'
+    TIMESTAMPED_SIGNATURE_HEADER = 'x-fopost-signature-256'
+    TIMESTAMP_HEADER = 'x-fopost-timestamp'
+    EVENT_HEADER = 'x-fopost-event'
+    DELIVERY_HEADER = 'x-fopost-delivery'
+    DEFAULT_TOLERANCE = 300
+
+    module_function
+
+    # Returns the parsed envelope as a {Fopost::WebhookEvent}, or raises
+    # {Fopost::WebhookSignatureError}.
+    #
+    # The timestamped signature is checked when `X-FoPost-Timestamp` is
+    # present and rejected when it is older than `tolerance` seconds; the
+    # plain body signature is accepted only when no timestamp was sent.
+    # `headers` may use any casing; a Rack `HTTP_X_FOPOST_*` key also works.
+    def verify(raw_body, headers, secret, tolerance: DEFAULT_TOLERANCE, now: nil)
+      raise WebhookSignatureError, 'fopost: a webhook secret is required' if secret.nil? || secret.to_s.empty?
+
+      body = raw_body.to_s
+      lookup = normalize_headers(headers)
+      timestamp = lookup[TIMESTAMP_HEADER]
+
+      if timestamp
+        check_timestamp(timestamp, tolerance, now)
+        expected = sign("#{timestamp}.#{body}", secret)
+        match = secure_equal(lookup[TIMESTAMPED_SIGNATURE_HEADER], expected)
+      else
+        match = secure_equal(lookup[SIGNATURE_HEADER], sign(body, secret))
+      end
+      raise WebhookSignatureError, 'fopost: webhook signature mismatch' unless match
+
+      parse(body)
+    end
+
+    # The header value FoPost sends for these exact bytes.
+    def sign(payload, secret)
+      "sha256=#{OpenSSL::HMAC.hexdigest('SHA256', secret.to_s, payload)}"
+    end
+
+    def check_timestamp(timestamp, tolerance, now)
+      seconds = Integer(timestamp.to_s.strip, exception: false)
+      raise WebhookSignatureError, 'fopost: webhook timestamp is not a number' unless seconds
+
+      drift = ((now || Time.now).to_i - seconds).abs
+      raise WebhookSignatureError, 'fopost: webhook timestamp outside tolerance' if drift > tolerance
+    end
+
+    def secure_equal(given, expected)
+      return false if given.nil?
+
+      given = given.to_s.strip
+      return false unless given.bytesize == expected.bytesize
+
+      OpenSSL.fixed_length_secure_compare(given, expected)
+    end
+
+    def parse(body)
+      data = JSON.parse(body)
+      raise WebhookSignatureError, 'fopost: webhook body is not an object' unless data.is_a?(Hash)
+
+      WebhookEvent.new(data)
+    rescue JSON::ParserError
+      raise WebhookSignatureError, 'fopost: webhook body is not JSON'
+    end
+
+    def normalize_headers(headers)
+      (headers || {}).each_with_object({}) do |(key, value), out|
+        name = key.to_s.downcase.tr('_', '-').sub(/\Ahttp-/, '')
+        out[name] = value.is_a?(Array) ? value.first : value
+      end
+    end
+
+    private_class_method :check_timestamp, :secure_equal, :parse, :normalize_headers
+  end
+end

data/lib/fopost.rb

@@ -6,11 +6,13 @@ require 'fopost/unset'
 require 'fopost/platforms'
 require 'fopost/model'
 require 'fopost/models'
+require 'fopost/file_part'
 require 'fopost/http/response'
 require 'fopost/http/transport'
 require 'fopost/http/net_http_transport'
 require 'fopost/http/client'
 require 'fopost/client'
+require 'fopost/webhooks'
 
 # Official Ruby SDK for the FoPost API.
 #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fopost
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - FoPost
@@ -22,21 +22,39 @@ files:
 - lib/fopost.rb
 - lib/fopost/client.rb
 - lib/fopost/errors.rb
+- lib/fopost/file_part.rb
 - lib/fopost/http/client.rb
+- lib/fopost/http/multipart.rb
 - lib/fopost/http/net_http_transport.rb
 - lib/fopost/http/response.rb
 - lib/fopost/http/transport.rb
 - lib/fopost/model.rb
 - lib/fopost/models.rb
 - lib/fopost/platforms.rb
+- lib/fopost/resources/account_groups.rb
 - lib/fopost/resources/accounts.rb
+- lib/fopost/resources/activity.rb
+- lib/fopost/resources/ads.rb
 - lib/fopost/resources/ai.rb
+- lib/fopost/resources/analytics.rb
 - lib/fopost/resources/base.rb
+- lib/fopost/resources/blog.rb
+- lib/fopost/resources/blogs.rb
+- lib/fopost/resources/broadcasts.rb
+- lib/fopost/resources/contacts.rb
+- lib/fopost/resources/google_ads.rb
+- lib/fopost/resources/google_business.rb
+- lib/fopost/resources/inbox.rb
+- lib/fopost/resources/knowledge.rb
 - lib/fopost/resources/labels.rb
+- lib/fopost/resources/media.rb
 - lib/fopost/resources/posts.rb
+- lib/fopost/resources/validate.rb
+- lib/fopost/resources/whatsapp.rb
 - lib/fopost/resources/workspaces.rb
 - lib/fopost/unset.rb
 - lib/fopost/version.rb
+- lib/fopost/webhooks.rb
 homepage: https://fopost.com
 licenses:
 - MIT