omnisocials 0.1.0

data/lib/omnisocials/resources/webhooks.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  module Resources
+    # Webhooks resource: manage event subscriptions (post.scheduled,
+    # post.published, post.failed).
+    #
+    # For verifying incoming deliveries, see OmniSocials::Webhooks.verify.
+    class Webhooks
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /webhooks - list webhook subscriptions.
+      def list
+        @client.request("GET", "/webhooks")
+      end
+
+      # GET /webhooks/{id} - fetch a single webhook subscription.
+      def get(webhook_id)
+        @client.request("GET", "/webhooks/#{webhook_id}")
+      end
+
+      # POST /webhooks - create a webhook subscription.
+      #
+      # `url` must be HTTPS. `events` is a non-empty subset of
+      # post.scheduled, post.published, post.failed. The signing `secret` is
+      # only returned once, in this response - store it.
+      def create(url:, events:)
+        @client.request(
+          "POST", "/webhooks",
+          json: { "url" => url, "events" => Array(events) }
+        )
+      end
+
+      # PATCH /webhooks/{id} - update url, events, or active state.
+      def update(webhook_id, url: nil, events: nil, is_active: nil)
+        body = Internal.drop_nil(
+          {
+            "url" => url,
+            "events" => events.nil? ? nil : Array(events),
+            "is_active" => is_active
+          }
+        )
+        @client.request("PATCH", "/webhooks/#{webhook_id}", json: body)
+      end
+
+      # DELETE /webhooks/{id} - delete a webhook. Returns nil (204).
+      def delete(webhook_id)
+        @client.request("DELETE", "/webhooks/#{webhook_id}")
+      end
+
+      # POST /webhooks/{id}/rotate-secret - rotate the signing secret.
+      #
+      # The new secret is only returned once, in this response.
+      def rotate_secret(webhook_id)
+        @client.request("POST", "/webhooks/#{webhook_id}/rotate-secret")
+      end
+    end
+  end
+end

data/lib/omnisocials/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  VERSION = "0.1.0"
+end

data/lib/omnisocials/webhooks.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module OmniSocials
+  # Webhook signature verification.
+  #
+  # OmniSocials signs every webhook delivery with HMAC-SHA256 (Stripe-style):
+  #
+  # - Header: X-OmniSocials-Signature: t=<unix>,v1=<hex>
+  # - Signed value: "{timestamp}.{raw_body}" (UTF-8), keyed with the
+  #   webhook's secret, hex digest.
+  module Webhooks
+    class << self
+      # Verify an OmniSocials webhook delivery and return the parsed event.
+      #
+      # payload   - the raw request body String, exactly as received. Do not
+      #             parse and re-serialize it first; the signature is over the
+      #             raw bytes.
+      # signature - the X-OmniSocials-Signature header value, of the form
+      #             t=<unix>,v1=<hex>.
+      # secret    - the webhook's signing secret (returned once when the
+      #             webhook is created, or via rotate_secret).
+      # tolerance - maximum allowed age (and future skew) of the signed
+      #             timestamp, in seconds. Defaults to 300. Pass nil to skip
+      #             the timestamp check (not recommended).
+      #
+      # Returns the parsed event as a Hash (string keys).
+      #
+      # Raises OmniSocials::WebhookVerificationError if the header is
+      # malformed, the timestamp is outside the tolerance window, or the
+      # signature does not match. Uses a constant-time comparison.
+      def verify(payload:, signature:, secret:, tolerance: 300)
+        unless payload.is_a?(String)
+          raise WebhookVerificationError,
+                "payload must be a String (the raw request body), got #{payload.class}."
+        end
+        unless signature.is_a?(String) && !signature.empty?
+          raise WebhookVerificationError, "Missing signature header."
+        end
+
+        timestamp = nil
+        candidates = []
+        signature.split(",").each do |pair|
+          key, _, value = pair.strip.partition("=")
+          case key
+          when "t"
+            begin
+              timestamp = Integer(value, 10)
+            rescue ArgumentError, TypeError
+              raise WebhookVerificationError,
+                    "Malformed signature header: non-integer timestamp."
+            end
+          when "v1"
+            candidates << value
+          end
+        end
+
+        if timestamp.nil?
+          raise WebhookVerificationError,
+                "Malformed signature header: missing 't=' timestamp."
+        end
+        if candidates.empty?
+          raise WebhookVerificationError,
+                "Malformed signature header: missing 'v1=' signature."
+        end
+
+        unless tolerance.nil?
+          drift = (Time.now.to_i - timestamp).abs
+          if drift > tolerance
+            raise WebhookVerificationError,
+                  "Timestamp outside the tolerance window (#{drift}s > #{tolerance}s). " \
+                  "The delivery may be stale or replayed."
+          end
+        end
+
+        signed_value = "#{timestamp}.".b + payload.b
+        expected = OpenSSL::HMAC.hexdigest("SHA256", secret, signed_value)
+
+        unless candidates.any? { |candidate| secure_compare(expected, candidate) }
+          raise WebhookVerificationError,
+                "Signature mismatch: the payload was not signed with this secret, " \
+                "or the body was modified in transit."
+        end
+
+        begin
+          event = JSON.parse(payload)
+        rescue JSON::ParserError
+          raise WebhookVerificationError, "Payload is not valid JSON."
+        end
+        unless event.is_a?(Hash)
+          raise WebhookVerificationError, "Payload is not a JSON object."
+        end
+        event
+      end
+
+      private
+
+      # Constant-time string comparison.
+      def secure_compare(expected, candidate)
+        return false unless candidate.is_a?(String)
+
+        if OpenSSL.respond_to?(:secure_compare)
+          OpenSSL.secure_compare(expected, candidate)
+        else
+          expected.bytesize == candidate.bytesize &&
+            OpenSSL.fixed_length_secure_compare(expected, candidate)
+        end
+      end
+    end
+  end
+end

data/lib/omnisocials.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Official Ruby SDK for the OmniSocials Public API.
+#
+# Docs: https://docs.omnisocials.com
+#
+#   require "omnisocials"
+#
+#   client = OmniSocials::Client.new  # reads OMNISOCIALS_API_KEY from env
+#   post = client.posts.create(
+#     content: "Hello from Ruby",
+#     channels: ["instagram", "linkedin"]
+#   )
+
+require_relative "omnisocials/version"
+require_relative "omnisocials/errors"
+require_relative "omnisocials/internal"
+require_relative "omnisocials/webhooks"
+require_relative "omnisocials/resources/posts"
+require_relative "omnisocials/resources/media"
+require_relative "omnisocials/resources/folders"
+require_relative "omnisocials/resources/accounts"
+require_relative "omnisocials/resources/analytics"
+require_relative "omnisocials/resources/locations"
+require_relative "omnisocials/resources/webhooks"
+require_relative "omnisocials/client"
+
+module OmniSocials
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: omnisocials
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- OmniSocials
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-15 00:00:00.000000000 Z
+dependencies: []
+description: Schedule and publish social media posts, upload media, and read analytics
+  across Instagram, Facebook, LinkedIn, YouTube, TikTok, X, Pinterest, Bluesky, Threads,
+  Mastodon, and Google Business via the OmniSocials Public API. Zero runtime dependencies
+  (Net::HTTP, OpenSSL, JSON).
+email:
+- hello@omnisocials.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/omnisocials.rb
+- lib/omnisocials/client.rb
+- lib/omnisocials/errors.rb
+- lib/omnisocials/internal.rb
+- lib/omnisocials/resources/accounts.rb
+- lib/omnisocials/resources/analytics.rb
+- lib/omnisocials/resources/folders.rb
+- lib/omnisocials/resources/locations.rb
+- lib/omnisocials/resources/media.rb
+- lib/omnisocials/resources/posts.rb
+- lib/omnisocials/resources/webhooks.rb
+- lib/omnisocials/version.rb
+- lib/omnisocials/webhooks.rb
+homepage: https://omnisocials.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://omnisocials.com
+  documentation_uri: https://docs.omnisocials.com
+  source_code_uri: https://github.com/OmniSocials/omnisocials-ruby
+  bug_tracker_uri: https://github.com/OmniSocials/omnisocials-ruby/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the OmniSocials Public API
+test_files: []