posthubify 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6aba91ab279c1953076139305c63fbf1b74818368796f6f9131d0179a745b0c3
+  data.tar.gz: 041db11a40a45c60ccedd45033e2d6c0f398de01f77c99143444c7223d08d521
+SHA512:
+  metadata.gz: 1f6f687df94c5a45fd36b5d0018dea79d8c14e3e78edf08a6729e3481e67c0e6cf34541d76a345493f1cc9a905ad83724dd05998365bffd6f17007ce8fa13226
+  data.tar.gz: 44c0b1e60be2554d52c9d9ec8e4003aed83e5556a5aa62354ecdd19b8479f8c4e9d7e9e29bc794fd04b2921f7b72ea95d4b13b4d33d8afee065ff08e549801b0

data/README.md

@@ -0,0 +1,76 @@
+# PostHubify Ruby SDK
+
+The official Ruby client for the PostHubify `/v1` API — a single gem for social media
+publishing, inbox, contacts, analytics, ads, and telecom (SMS/OTP).
+
+- **Zero runtime dependencies** — Ruby standard library only (`net/http`).
+- **Full surface** — covers all 190+ operations of the `/v1` spec one-to-one (verified by a contract test).
+- Ruby 2.6+
+
+## Installation
+
+```ruby
+gem install posthubify
+```
+
+## Quick start
+
+```ruby
+require 'posthubify'
+
+ph = Posthubify::Client.new(api_key: 'sk_...', base_url: 'https://api.posthubify.com/v1')
+
+# Connection test
+ph.ping  # => {"pong"=>true, "version"=>"v1", ...}
+
+# Create a post
+ph.posts.create({ 'content' => 'Hello world!', 'accountIds' => ['acc_1'] })
+
+# Safe retry (Idempotency-Key — posts/sms/otp/ads/broadcasts)
+require 'securerandom'
+key = SecureRandom.uuid
+ph.posts.create({ 'content' => 'Launch!', 'accountIds' => ['acc_1'] }, idempotency_key: key)
+
+# Inbox analytics
+ph.inbox_analytics.volume(from_date: '2026-06-01', to_date: '2026-06-14')
+
+# Error handling
+begin
+  ph.posts.get('missing')
+rescue Posthubify::Error => e
+  puts [e.status, e.code, e.message].inspect  # [404, nil, "..."]
+end
+```
+
+## Resource groups
+
+The exact same surface as the Node/Python SDKs, with snake_case accessors:
+
+`profiles` · `accounts` · `posts` · `media` · `tools` · `ads` · `insights` ·
+`platform_analytics` · `inbox_analytics` · `inbox` · `comments` · `reviews` ·
+`contacts` · `automations` · `broadcasts` · `sequences` · `webhooks` · `api_keys` ·
+`queue` (`.schedules`) · `account_groups` · `engagement` (`.x`) · `users` ·
+`invite_tokens` · `numbers` · `senders` · `sms` · `otp`
+
+Top level: `ph.openapi`, `ph.ping`, `ph.me`, `ph.analytics`, `ph.analytics_posts`,
+`ph.analytics_timeseries`, `ph.logs`, `ph.usage`.
+
+## Media upload
+
+```ruby
+content = File.binread('logo.png')
+asset = ph.media.upload(content, 'logo.png')  # => {"assetId"=>..., "url"=>...}
+ph.posts.create({ 'content' => 'New!', 'accountIds' => ['acc_1'], 'mediaAssetId' => asset['assetId'] })
+```
+
+## Development
+
+```bash
+ruby packages/ruby-sdk/test/test_contract.rb   # SDK ↔ spec contract test
+```
+
+The contract test verifies that the endpoint path produced by every SDK method is defined in the OpenAPI spec.
+
+## License
+
+MIT

data/lib/posthubify/client.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Posthubify
+  # PostHubify /v1 API client. All resource groups are exposed as snake_case readers.
+  class Client
+    attr_reader :profiles, :accounts, :posts, :media, :tools, :ads, :insights,
+                :platform_analytics, :inbox_analytics, :inbox, :comments, :reviews,
+                :contacts, :automations, :comment_automations, :workflows, :broadcasts, :sequences, :webhooks, :api_keys,
+                :queue, :account_groups, :engagement, :users, :invite_tokens,
+                :numbers, :senders, :sms, :otp,
+                :custom_fields, :whatsapp, :gmb, :discord, :discovery
+
+    # transport: injectable for tests (Node opts.fetch equivalent).
+    def initialize(api_key: nil, base_url: Transport::DEFAULT_BASE, timeout: 30, transport: nil)
+      @http = transport || Transport.new(api_key: api_key, base_url: base_url, timeout: timeout)
+
+      @profiles = ProfilesResource.new(@http)
+      @accounts = AccountsResource.new(@http)
+      @posts = PostsResource.new(@http)
+      @media = MediaResource.new(@http)
+      @tools = ToolsResource.new(@http)
+      @ads = AdsResource.new(@http)
+      @insights = InsightsResource.new(@http)
+      @platform_analytics = PlatformAnalyticsResource.new(@http)
+      @inbox_analytics = InboxAnalyticsResource.new(@http)
+      @inbox = InboxResource.new(@http)
+      @comments = CommentsResource.new(@http)
+      @reviews = ReviewsResource.new(@http)
+      @contacts = ContactsResource.new(@http)
+      @automations = AutomationsResource.new(@http)
+      @comment_automations = CommentAutomationsResource.new(@http)
+      @workflows = WorkflowsResource.new(@http)
+      @broadcasts = BroadcastsResource.new(@http)
+      @sequences = SequencesResource.new(@http)
+      @webhooks = WebhooksResource.new(@http)
+      @api_keys = ApiKeysResource.new(@http)
+      @queue = QueueResource.new(@http)
+      @account_groups = AccountGroupsResource.new(@http)
+      @engagement = EngagementResource.new(@http)
+      @users = UsersResource.new(@http)
+      @invite_tokens = InviteTokensResource.new(@http)
+      @numbers = NumbersResource.new(@http)
+      @senders = SendersResource.new(@http)
+      @sms = SmsResource.new(@http)
+      @otp = OtpResource.new(@http)
+      @custom_fields = CustomFieldsResource.new(@http)
+      @whatsapp = WhatsAppResource.new(@http)
+      @gmb = GmbResource.new(@http)
+      @discord = DiscordResource.new(@http)
+      @discovery = DiscoveryResource.new(@http)
+    end
+
+    # --- top-level endpoints ---
+    def openapi
+      @http.req('GET', '/openapi.json')
+    end
+
+    def ping
+      @http.data('GET', '/ping')
+    end
+
+    def me
+      @http.data('GET', '/me')
+    end
+
+    # AI content generation (F1) — command → per-platform draft + variants (multi-language).
+    def generate(command, platforms, variants: nil, context: nil, max_chars: nil)
+      @http.data('POST', '/generate', body: {
+        'command' => command, 'platforms' => platforms, 'variants' => variants,
+        'context' => context, 'maxChars' => max_chars,
+      })
+    end
+
+    # Subtitle generation (F4) — text → timed SRT/VTT (pure conversion, no AI/charge; a read key is enough).
+    # @param text [String] text to turn into subtitles (≤20000 characters)
+    # @param format [String] 'srt' or 'vtt' (default 'srt')
+    # @param duration_sec [Float, nil] if given, cues are distributed proportionally over this duration (audio-synced; ≤86400)
+    # @param max_chars_per_line [Integer, nil] max characters per line (10–120, default 42)
+    # @param max_lines_per_cue [Integer, nil] max lines per cue (1–4, default 2)
+    # @param chars_per_sec [Float, nil] reading speed when no duration is given (may be fractional, e.g. 15.5)
+    # @param gap_ms [Integer, nil] gap between cues (ms, default 80)
+    def subtitles(text, format: 'srt', duration_sec: nil, max_chars_per_line: nil,
+                  max_lines_per_cue: nil, chars_per_sec: nil, gap_ms: nil)
+      @http.data('POST', '/subtitles', body: {
+        'text' => text, 'format' => format, 'durationSec' => duration_sec,
+        'maxCharsPerLine' => max_chars_per_line, 'maxLinesPerCue' => max_lines_per_cue,
+        'charsPerSec' => chars_per_sec, 'gapMs' => gap_ms,
+      })
+    end
+
+    # Promo video render (F4) — remote image (+optional audio/subtitle) → branded video (ffmpeg) → R2 URL.
+    # @param image_url [String] publicly-accessible https image URL
+    # @param format [String] video ratio: '9:16' | '1:1' | '16:9'
+    # @param audio_url [String, nil] voiceover (mp3) URL; if given, the video duration is matched to the audio
+    # @param subtitle_text [String, nil] subtitle text to burn into the video
+    # @param subtitle_rtl [Boolean, nil] whether the subtitle is right-to-left (Arabic, etc.)
+    # HEAVY operation (write permission + low rate limit). Media is downloaded SSRF-protected (https + type + ≤25MB).
+    def videos(image_url, format, audio_url: nil, subtitle_text: nil, subtitle_rtl: nil,
+               bumper_duration_sec: nil, main_duration_sec: nil)
+      @http.data('POST', '/videos', body: {
+        'imageUrl' => image_url, 'format' => format, 'audioUrl' => audio_url,
+        'subtitleText' => subtitle_text, 'subtitleRtl' => subtitle_rtl,
+        'bumperDurationSec' => bumper_duration_sec, 'mainDurationSec' => main_duration_sec,
+      })
+    end
+
+    def analytics
+      @http.data('GET', '/analytics')
+    end
+
+    # Post analytics list — source: 'external' is synced from the platform, not PostHubify (B5).
+    def analytics_posts(platform: nil, account_id: nil, source: nil, limit: nil, cursor: nil)
+      @http.req('GET', '/analytics/posts', query: {
+                  'platform' => platform, 'accountId' => account_id, 'source' => source,
+                  'limit' => limit, 'cursor' => cursor
+                })
+    end
+
+    # Stored daily metric time series (account/post/inbox aggregates).
+    def analytics_timeseries(days: nil, platform: nil, account_id: nil, from_date: nil, to_date: nil, source: nil)
+      @http.data('GET', '/analytics/timeseries', query: {
+                   'days' => days, 'platform' => platform, 'accountId' => account_id,
+                   'fromDate' => from_date, 'toDate' => to_date, 'source' => source
+                 })
+    end
+
+    def usage
+      @http.data('GET', '/usage')
+    end
+
+    def logs(limit: nil, category: nil, status: nil, platform: nil, days: nil)
+      @http.data('GET', '/logs', query: {
+                   'limit' => limit, 'category' => category, 'status' => status,
+                   'platform' => platform, 'days' => days
+                 })
+    end
+  end
+end

data/lib/posthubify/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Posthubify
+  # Raised when an API request returns a non-2xx status.
+  #
+  #   begin
+  #     ph.posts.get("missing")
+  #   rescue Posthubify::Error => e
+  #     puts [e.status, e.code, e.message].inspect
+  #   end
+  class Error < StandardError
+    attr_reader :status, :code, :body
+
+    def initialize(status, message, code = nil, body = nil)
+      super(message)
+      @status = status
+      @code = code
+      @body = body
+    end
+  end
+end

data/lib/posthubify/http.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'securerandom'
+
+module Posthubify
+  # HTTP transport layer — standard library only (net/http). Bearer auth, JSON body,
+  # multipart upload, `{ "data" => ... }` envelope unwrapping, non-2xx → Posthubify::Error.
+  class Transport
+    DEFAULT_BASE = 'http://localhost:8787/v1'
+    USER_AGENT = 'posthubify-ruby/0.1.0'
+
+    def initialize(api_key:, base_url: DEFAULT_BASE, timeout: 30)
+      raise ArgumentError, 'api_key required (sk_…)' if api_key.nil? || api_key.empty?
+
+      @key = api_key
+      @base = base_url.sub(%r{/\z}, '')
+      @timeout = timeout
+    end
+
+    # Raw request: 2xx → parsed body, otherwise Posthubify::Error.
+    # files: [field_name, bytes, file_name] — multipart upload (media.upload).
+    def req(method, path, query: nil, body: nil, files: nil, idempotency_key: nil)
+      uri = URI("#{@base}#{path}")
+      unless query.nil?
+        pairs = query.reject { |_k, v| v.nil? }
+        uri.query = URI.encode_www_form(pairs) unless pairs.empty?
+      end
+
+      request = build_request(method, uri, body, files, idempotency_key)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.read_timeout = @timeout
+      http.open_timeout = @timeout
+
+      response = http.request(request)
+      parsed = parse(response.body)
+      status = response.code.to_i
+      unless (200..299).cover?(status)
+        message = (parsed.is_a?(Hash) && parsed['error']) || "HTTP #{status}"
+        code = parsed.is_a?(Hash) ? parsed['code'] : nil
+        raise Posthubify::Error.new(status, message, code, parsed)
+      end
+      parsed
+    rescue SocketError, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout => e
+      raise Posthubify::Error.new(0, "Network error: #{e.message}")
+    end
+
+    # Unwraps the `{ "data" => ... }` envelope.
+    def data(method, path, query: nil, body: nil, files: nil, idempotency_key: nil)
+      result = req(method, path, query: query, body: body, files: files, idempotency_key: idempotency_key)
+      result.is_a?(Hash) && result.key?('data') ? result['data'] : result
+    end
+
+    private
+
+    def build_request(method, uri, body, files, idempotency_key)
+      klass = {
+        'GET' => Net::HTTP::Get, 'POST' => Net::HTTP::Post, 'PUT' => Net::HTTP::Put,
+        'PATCH' => Net::HTTP::Patch, 'DELETE' => Net::HTTP::Delete
+      }.fetch(method.to_s.upcase)
+      request = klass.new(uri)
+      request['Authorization'] = "Bearer #{@key}"
+      request['User-Agent'] = USER_AGENT
+      request['Accept'] = 'application/json'
+      request['Idempotency-Key'] = idempotency_key if idempotency_key
+
+      if files
+        field, content, filename = files
+        boundary = SecureRandom.hex(16)
+        request['Content-Type'] = "multipart/form-data; boundary=#{boundary}"
+        request.body = multipart_body(field, content, filename, boundary)
+      elsif !body.nil?
+        request['Content-Type'] = 'application/json'
+        request.body = JSON.generate(body)
+      end
+      request
+    end
+
+    def multipart_body(field, content, filename, boundary)
+      mime = case File.extname(filename).downcase
+             when '.png' then 'image/png'
+             when '.jpg', '.jpeg' then 'image/jpeg'
+             when '.mp4' then 'video/mp4'
+             else 'application/octet-stream'
+             end
+      "--#{boundary}\r\n" \
+        "Content-Disposition: form-data; name=\"#{field}\"; filename=\"#{filename}\"\r\n" \
+        "Content-Type: #{mime}\r\n\r\n" + content + "\r\n--#{boundary}--\r\n"
+    end
+
+    def parse(raw)
+      return nil if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/posthubify/resources/accounts.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Posthubify
+  # Profiles (Node sdk .profiles) — workspace/brand separation.
+  class ProfilesResource
+    def initialize(http)
+      @http = http
+    end
+
+    # List all profiles.
+    def list
+      @http.data('GET', '/profiles')
+    end
+
+    # Get a single profile.
+    def get(id)
+      @http.data('GET', "/profiles/#{id}")
+    end
+
+    # Create a profile (input: { name }).
+    def create(input)
+      @http.data('POST', '/profiles', body: input)
+    end
+
+    # Update a profile (input: name/description/color/isDefault).
+    def update(id, input)
+      @http.data('PATCH', "/profiles/#{id}", body: input)
+    end
+
+    # Delete a profile.
+    def delete(id)
+      @http.data('DELETE', "/profiles/#{id}")
+    end
+  end
+
+  # Connected platform accounts (Node sdk .accounts) — health, follower stats, OAuth linking.
+  class AccountsResource
+    def initialize(http)
+      @http = http
+    end
+
+    # List accounts (filter: profile_id/platform/is_active).
+    def list(profile_id: nil, platform: nil, is_active: nil)
+      @http.data('GET', '/accounts', query: {
+                   'profileId' => profile_id,
+                   'platform' => platform,
+                   'isActive' => is_active
+                 })
+    end
+
+    # Update an account (input: label/profileId/isActive).
+    def update(id, input)
+      @http.data('PATCH', "/accounts/#{id}", body: input)
+    end
+
+    # Health of all accounts + summary (token expiry, reconnection needs).
+    def health
+      @http.data('GET', '/accounts/health')
+    end
+
+    # Health report for a single account.
+    def health_of(id)
+      @http.data('GET', "/accounts/#{id}/health")
+    end
+
+    # Pinterest boards (for posts.create options.board). 400 on an unsupported platform.
+    def boards(id)
+      @http.data('GET', "/accounts/#{id}/boards")
+    end
+
+    # Reddit subreddit flairs (for posts.create options.flairId). 400 on an unsupported platform.
+    def flairs(id)
+      @http.data('GET', "/accounts/#{id}/flairs")
+    end
+
+    # ── Entity pickers + publishing defaults (D8) ──
+    def reddit_subreddits(id)
+      @http.data('GET', "/accounts/#{id}/reddit-subreddits")
+    end
+
+    def set_default_subreddit(id, subreddit)
+      @http.data('PUT', "/accounts/#{id}/reddit-subreddits", body: { 'subreddit' => subreddit })
+    end
+
+    def youtube_playlists(id)
+      @http.data('GET', "/accounts/#{id}/youtube-playlists")
+    end
+
+    def set_default_playlist(id, playlist_id)
+      @http.data('PUT', "/accounts/#{id}/youtube-playlists", body: { 'playlistId' => playlist_id })
+    end
+
+    def linkedin_organizations(id)
+      @http.data('GET', "/accounts/#{id}/linkedin-organizations")
+    end
+
+    def pinterest_boards(id)
+      @http.data('GET', "/accounts/#{id}/pinterest-boards")
+    end
+
+    def set_default_board(id, board_id)
+      @http.data('PUT', "/accounts/#{id}/pinterest-boards", body: { 'boardId' => board_id })
+    end
+
+    # ── Bot command menu (A1) — Telegram bot "/" commands (per account). ──
+    # Get the bot command menu (Telegram getMyCommands). scope/language_code optional.
+    def bot_commands(id, scope: nil, language_code: nil)
+      @http.data('GET', "/accounts/#{id}/bot-commands", query: {
+                   'scope' => scope,
+                   'languageCode' => language_code
+                 })
+    end
+
+    # Set the bot command menu (Telegram setMyCommands).
+    def set_bot_commands(id, commands, scope: nil, language_code: nil)
+      @http.data('PUT', "/accounts/#{id}/bot-commands", body: {
+                   'commands' => commands,
+                   'scope' => scope,
+                   'languageCode' => language_code
+                 })
+    end
+
+    # Clear the bot command menu (Telegram deleteMyCommands).
+    def delete_bot_commands(id, scope: nil, language_code: nil)
+      @http.data('DELETE', "/accounts/#{id}/bot-commands", query: {
+                   'scope' => scope,
+                   'languageCode' => language_code
+                 })
+    end
+
+    # Follower history + growth across all accounts (granularity: daily|weekly|monthly).
+    def follower_stats_all(days: nil, granularity: nil)
+      @http.data('GET', '/accounts/follower-stats', query: {
+                   'days' => days,
+                   'granularity' => granularity
+                 })
+    end
+
+    # Follower history + change for a single account (granularity: daily|weekly|monthly).
+    def follower_stats(id, days: nil, granularity: nil)
+      @http.data('GET', "/accounts/#{id}/follower-stats", query: {
+                   'days' => days,
+                   'granularity' => granularity
+                 })
+    end
+
+    # Delete an account.
+    def delete(id)
+      @http.data('DELETE', "/accounts/#{id}")
+    end
+
+    # OAuth connect URL — the user visits it in a browser (query: profile_id).
+    def connect_url(platform, profile_id: nil)
+      @http.data('GET', "/connect/#{platform}", query: { 'profileId' => profile_id })
+    end
+
+    # ── Headless credential connect (D8 cp2) — linking without OAuth. ──
+    def connect_bluesky(handle, app_password, profile_id: nil, label: nil)
+      @http.data('POST', '/connect/bluesky/credentials', body: { 'handle' => handle, 'appPassword' => app_password, 'profileId' => profile_id, 'label' => label })
+    end
+
+    def connect_telegram(bot_token, chat_id, profile_id: nil, label: nil)
+      @http.data('POST', '/connect/telegram', body: { 'botToken' => bot_token, 'chatId' => chat_id, 'profileId' => profile_id, 'label' => label })
+    end
+
+    def connect_whatsapp(access_token, phone_number_id, recipients, waba_id: nil, profile_id: nil, label: nil)
+      @http.data('POST', '/connect/whatsapp/credentials', body: { 'accessToken' => access_token, 'phoneNumberId' => phone_number_id, 'recipients' => recipients, 'wabaId' => waba_id, 'profileId' => profile_id, 'label' => label })
+    end
+
+    def connect_line(channel_access_token, channel_secret, profile_id: nil, label: nil)
+      @http.data('POST', '/connect/line/credentials', body: { 'channelAccessToken' => channel_access_token, 'channelSecret' => channel_secret, 'profileId' => profile_id, 'label' => label })
+    end
+
+    # ── Headless OAuth connect (D8 cp3) — tempToken start/status. ──
+    # Start headless OAuth → {tempToken, authUrl}: open authUrl in a browser, then poll status.
+    def connect_oauth_start(platform, profile_id: nil, label: nil)
+      @http.data('POST', '/connect/oauth/start', body: { 'platform' => platform, 'profileId' => profile_id, 'label' => label })
+    end
+
+    # Headless OAuth status (poll): pending | connected (+account) | error.
+    def connect_oauth_status(temp_token)
+      @http.data('GET', '/connect/oauth/status', query: { 'tempToken' => temp_token })
+    end
+  end
+end