fopost 0.1.0

data/lib/fopost/http/transport.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Fopost
+  module HTTP
+    # The seam the SDK sends requests through.
+    #
+    # Implement `call` and pass an instance as `transport:` to swap in your own
+    # HTTP stack, or to stub the network in tests.
+    #
+    #   class MyTransport
+    #     def call(method:, url:, headers:, body:)
+    #       Fopost::HTTP::Response.new(status: 200, body: '{}')
+    #     end
+    #   end
+    module Transport
+      def call(method:, url:, headers:, body:)
+        raise NotImplementedError, 'a transport must implement #call'
+      end
+    end
+  end
+end

data/lib/fopost/model.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Fopost
+  # Base for every response model.
+  #
+  # The API is not consistent about its wire casing — posts come back
+  # snake_case, accounts camelCase, workspaces a mix — so every key is
+  # normalised to a snake_case symbol before it is read. Unknown keys are kept
+  # on {#raw} rather than dropped, so a server-side addition never breaks a
+  # client.
+  class Model
+    class << self
+      def attribute_types
+        @attribute_types ||= superclass.respond_to?(:attribute_types) ? superclass.attribute_types.dup : {}
+      end
+
+      # `type` is nil (pass through), :time, :hash, a Model subclass, or a
+      # one-element array holding a Model subclass.
+      def attribute(name, type = nil)
+        attribute_types[name] = type
+        define_method(name) { @attributes[name] }
+      end
+
+      def snake(key)
+        key.to_s
+           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+           .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+           .downcase
+           .to_sym
+      end
+
+      def normalize(data)
+        return {} unless data.is_a?(Hash)
+
+        data.each_with_object({}) { |(key, value), out| out[snake(key)] = value }
+      end
+
+      def coerce(type, value)
+        case type
+        when nil then value
+        when :time then parse_time(value)
+        when :hash then value.is_a?(Hash) ? value : {}
+        when Array
+          member = type.first
+          value.is_a?(Array) ? value.map { |item| member.new(item) } : []
+        else
+          value.is_a?(Hash) ? type.new(value) : nil
+        end
+      end
+
+      def parse_time(value)
+        case value
+        when Time then value
+        when String then Time.iso8601(value) rescue (Time.parse(value) rescue nil)
+        end
+      end
+    end
+
+    # The decoded body exactly as the API sent it.
+    attr_reader :raw
+
+    def initialize(data = {})
+      @raw = data.is_a?(Hash) ? data : {}
+      normalized = self.class.normalize(@raw)
+      @attributes = {}
+      self.class.attribute_types.each do |name, type|
+        @attributes[name] = self.class.coerce(type, normalized[name])
+      end
+      @normalized = normalized
+    end
+
+    # Read a field the SDK does not model yet, by either wire spelling.
+    def [](key)
+      name = self.class.snake(key)
+      return @attributes[name] if @attributes.key?(name)
+
+      @normalized[name]
+    end
+
+    def to_h
+      @attributes.dup
+    end
+
+    def ==(other)
+      other.class == self.class && other.raw == raw
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, raw].hash
+    end
+
+    def inspect
+      shown = @attributes.reject { |_, value| value.nil? || value == [] || value == {} }
+      fields = shown.map { |name, value| "#{name}=#{value.inspect}" }.join(' ')
+      "#<#{self.class.name}#{" #{fields}" unless fields.empty?}>"
+    end
+  end
+end

data/lib/fopost/models.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require 'fopost/model'
+
+module Fopost
+  class MediaItem < Model
+    attribute :type
+    attribute :name
+    attribute :url
+    attribute :size
+    attribute :alt
+    attribute :thumbnail
+  end
+
+  # One block of a post. A thread is several blocks in order.
+  class ContentBlock < Model
+    attribute :id
+    attribute :text
+    attribute :media, [MediaItem]
+    attribute :position
+  end
+
+  # A connected social account. Named so it does not read as a user account.
+  class SocialAccount < Model
+    attribute :id
+    attribute :workspace_id
+    attribute :platform
+    attribute :username
+    attribute :name
+    attribute :avatar
+    attribute :active
+    attribute :is_primary
+    attribute :health_status
+    attribute :last_health_check, :time
+  end
+
+  # An account a post is targeted at, plus its per-account delivery state.
+  class PostAccount < Model
+    attribute :id
+    attribute :platform
+    attribute :username
+    attribute :name
+    attribute :avatar
+    attribute :publish_status
+    attribute :posted_at, :time
+    attribute :platform_post_id
+    attribute :external_url
+    attribute :error_code
+    attribute :error_message
+    attribute :attempts
+    attribute :max_attempts
+  end
+
+  class Label < Model
+    attribute :id
+    attribute :name
+    attribute :color
+    attribute :workspace, :hash
+  end
+
+  class Post < Model
+    attribute :id
+    attribute :workspace_id
+    attribute :status
+    attribute :content_type
+    attribute :schedule_at, :time
+    attribute :title
+    attribute :summary
+    attribute :repeatable
+    attribute :repeatable_times
+    attribute :repeatable_gap
+    attribute :repeatable_gap_unit
+    attribute :remaining_posts
+    attribute :auto_plug
+    attribute :auto_plug_content
+    attribute :approved_at, :time
+    attribute :rejection_reason
+    attribute :content, [ContentBlock]
+    attribute :accounts, [PostAccount]
+    attribute :labels, [Label]
+    attribute :settings, :hash
+    attribute :created_at, :time
+    attribute :updated_at, :time
+  end
+
+  class Workspace < Model
+    attribute :id
+    attribute :name
+    attribute :slug
+    attribute :type
+    attribute :logo
+    attribute :website
+    attribute :timezone
+    attribute :country
+    attribute :description
+    attribute :language
+    attribute :require_approval
+    attribute :ai_alt_text_enabled
+    attribute :brand_color
+    attribute :role
+    attribute :created_at, :time
+    attribute :accounts, [SocialAccount]
+  end
+
+  # One post-to-account delivery attempt.
+  class Delivery < Model
+    attribute :id
+    attribute :account_id
+    attribute :status
+    attribute :platform
+    attribute :username
+    attribute :account_name
+    attribute :error_code
+    attribute :error_message
+    attribute :attempts
+    attribute :max_attempts
+    attribute :scheduled_publish_at, :time
+    attribute :delay_reason
+    attribute :delay_message
+    attribute :posted_at, :time
+    attribute :last_attempt_at, :time
+    attribute :platform_post_id
+    attribute :external_url
+  end
+
+  class PageMeta < Model
+    attribute :current_page
+    attribute :per_page
+    attribute :total
+    attribute :last_page
+    attribute :from
+    attribute :to
+  end
+
+  # One page of a list endpoint: its items plus the pagination meta.
+  class Page
+    include Enumerable
+
+    attr_reader :items, :meta
+
+    def initialize(items: [], meta: PageMeta.new)
+      @items = items
+      @meta = meta
+    end
+
+    def each(&block)
+      return items.each unless block
+
+      items.each(&block)
+      self
+    end
+
+    def [](index)
+      items[index]
+    end
+
+    def size
+      items.size
+    end
+    alias length size
+    alias count size
+
+    def empty?
+      items.empty?
+    end
+
+    def inspect
+      "#<Fopost::Page items=#{items.size} total=#{meta.total.inspect}>"
+    end
+  end
+
+  # Credits charged by one AI call, and what is left afterwards.
+  class AiCredits < Model
+    attribute :charged
+    attribute :remaining
+  end
+
+  class AiCreditBalance < Model
+    attribute :credits_remaining
+    attribute :credits_used
+    attribute :credits_total
+    attribute :period_start, :time
+    attribute :period_end, :time
+  end
+
+  class CaptionResult < Model
+    attribute :caption
+    attribute :credits, AiCredits
+  end
+
+  class RewriteVariant < Model
+    attribute :platform
+    attribute :content
+    attribute :credits
+  end
+
+  class RewriteResult < Model
+    attribute :results, [RewriteVariant]
+    attribute :credits, AiCredits
+  end
+
+  class RepurposeResult < Model
+    attribute :url
+    attribute :title
+    attribute :posts, :hash
+    attribute :credits, AiCredits
+  end
+end

data/lib/fopost/platforms.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Fopost
+  # Every platform the API can publish to. Model fields stay plain strings, so a
+  # platform added server-side still parses on an older SDK.
+  PLATFORMS = %w[
+    twitter
+    linkedin
+    facebook
+    instagram
+    instagram-business
+    telegram
+    twitch
+    discord
+    slack
+    reddit
+    pinterest
+    tumblr
+    dribbble
+    mewe
+    tiktok
+    youtube
+    bluesky
+    threads
+    mastodon
+    lemmy
+    devto
+    hashnode
+    medium
+    substack
+    google-business
+    kick
+    listmonk
+    wordpress
+    nostr
+    whop
+    skool
+  ].freeze
+
+  POST_STATUSES = %w[
+    draft
+    pending_approval
+    scheduled
+    publishing
+    published
+    failed
+    cancelled
+  ].freeze
+end

data/lib/fopost/resources/accounts.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Fopost
+  module Resources
+    # `client.accounts` — the social accounts connected to a workspace.
+    class Accounts < Base
+      # Connected accounts, across every workspace unless one is named.
+      def list(workspace_id: nil)
+        # This endpoint reads a camelCase query param; posts and labels use snake.
+        parse_list(SocialAccount, unwrap(http.get('/accounts', { 'workspaceId' => workspace_id })))
+      end
+
+      def get(account_id)
+        SocialAccount.new(unwrap(http.get("/accounts/#{account_id}")))
+      end
+
+      # Token validity and last-check detail for one account.
+      def health(account_id)
+        as_hash(unwrap(http.get("/accounts/#{account_id}/health")))
+      end
+    end
+  end
+end

data/lib/fopost/resources/ai.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Fopost
+  module Resources
+    # `client.ai` — caption assist, per-platform rewriting, and blog fan-out.
+    #
+    # Every call spends AI credits. Check the balance with {#credits}; a
+    # {Fopost::PaymentRequiredError} means the plan has none left.
+    class Ai < Base
+      # Credits remaining, used, and total for the current billing period.
+      def credits
+        AiCreditBalance.new(unwrap(http.get('/ai/credits')))
+      end
+
+      def generate_caption(current_caption: nil, image_urls: nil, platforms: nil,
+                           char_limit: nil, workspace_id: nil, brand_voice_id: nil)
+        body = compact_nil(
+          'current_caption' => current_caption,
+          'image_urls' => image_urls&.to_a,
+          'platforms' => platforms&.to_a,
+          'char_limit' => char_limit,
+          'workspace_id' => workspace_id,
+          'brand_voice_id' => brand_voice_id
+        )
+        CaptionResult.new(unwrap(http.post('/ai/generate-caption', body)))
+      end
+
+      # Rewrite one draft for each target platform. Costs 1 credit per platform.
+      def rewrite(content:, platforms:, tone: nil, workspace_id: nil, brand_voice_id: nil)
+        body = compact_nil(
+          'content' => content,
+          'platforms' => platforms.to_a,
+          'tone' => tone,
+          'workspace_id' => workspace_id,
+          'brand_voice_id' => brand_voice_id
+        )
+        RewriteResult.new(unwrap(http.post('/ai/rewrite', body)))
+      end
+
+      # Turn an article URL into a post for each platform, in one call.
+      def repurpose_url(url:, platforms:, workspace_id: nil, brand_voice_id: nil)
+        body = compact_nil(
+          'url' => url,
+          'platforms' => platforms.to_a,
+          'workspace_id' => workspace_id,
+          'brand_voice_id' => brand_voice_id
+        )
+        RepurposeResult.new(unwrap(http.post('/ai/repurpose-url', body)))
+      end
+    end
+  end
+end

data/lib/fopost/resources/base.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'fopost/unset'
+
+module Fopost
+  module Resources
+    class Base
+      def initialize(http)
+        @http = http
+      end
+
+      private
+
+      attr_reader :http
+
+      def unwrap(body)
+        Fopost::HTTP::Client.unwrap(body)
+      end
+
+      def parse_list(model, data)
+        data.is_a?(Array) ? data.map { |item| model.new(item) } : []
+      end
+
+      def as_hash(body)
+        body.is_a?(Hash) ? body : { 'data' => body }
+      end
+
+      # Strip the keys the caller never passed, so a PUT stays a partial update.
+      def compact_unset(body)
+        body.reject { |_, value| UNSET.equal?(value) }
+      end
+
+      def compact_nil(body)
+        body.compact
+      end
+
+      def iso8601(value)
+        case value
+        when nil then nil
+        when String then value
+        when Time then value.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+        else
+          value.respond_to?(:iso8601) ? value.iso8601 : value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/fopost/resources/labels.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Fopost
+  module Resources
+    # `client.labels` — workspace labels you can attach to posts.
+    class Labels < Base
+      def list(workspace_id: nil)
+        parse_list(Label, unwrap(http.get('/labels', { 'workspace_id' => workspace_id })))
+      end
+    end
+  end
+end

data/lib/fopost/resources/posts.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Fopost
+  module Resources
+    # `client.posts` — create, schedule, publish, and inspect posts.
+    class Posts < Base
+      # One page of posts. The result is Enumerable over its items.
+      def list(workspace_id: nil, status: nil, search: nil, page: 1, per_page: 30, sort: nil)
+        body = http.get(
+          '/posts',
+          {
+            'workspace_id' => workspace_id,
+            'status' => status,
+            'search' => search,
+            'page' => page,
+            'per_page' => per_page,
+            'sort' => sort
+          }
+        )
+
+        items = parse_list(Post, body.is_a?(Hash) ? body['data'] : body)
+        raw_meta = body.is_a?(Hash) ? body['meta'] : nil
+        Page.new(items: items, meta: PageMeta.new(raw_meta.is_a?(Hash) ? raw_meta : {}))
+      end
+
+      # Walk every matching post, fetching one page at a time.
+      def each(workspace_id: nil, status: nil, search: nil, per_page: 30, sort: nil, start_page: 1, &block)
+        unless block
+          return enum_for(:each, workspace_id: workspace_id, status: status, search: search,
+                                 per_page: per_page, sort: sort, start_page: start_page)
+        end
+
+        each_page(workspace_id: workspace_id, status: status, search: search,
+                  per_page: per_page, sort: sort, start_page: start_page) do |page|
+          page.items.each(&block)
+        end
+      end
+
+      # The same walk as {#each}, but yields whole pages so the meta stays reachable.
+      def each_page(workspace_id: nil, status: nil, search: nil, per_page: 30, sort: nil, start_page: 1)
+        unless block_given?
+          return enum_for(:each_page, workspace_id: workspace_id, status: status, search: search,
+                                      per_page: per_page, sort: sort, start_page: start_page)
+        end
+
+        page_number = start_page
+        loop do
+          page = list(workspace_id: workspace_id, status: status, search: search,
+                      page: page_number, per_page: per_page, sort: sort)
+          return if page.items.empty?
+
+          yield page
+
+          last_page = page.meta.last_page
+          return if last_page && page_number >= last_page
+          return if last_page.nil? && page.items.size < per_page
+
+          page_number += 1
+        end
+      end
+
+      def get(post_id)
+        Post.new(unwrap(http.get("/posts/#{post_id}")))
+      end
+
+      # Create a draft or a scheduled post.
+      #
+      # `status` is "draft" or "scheduled"; a scheduled post needs `schedule_at`.
+      # To send a post out now, create it and call {#publish}.
+      def create(workspace_id:, content:, accounts: [], status: 'draft', schedule_at: nil,
+                 labels: nil, title: nil, summary: nil, content_type: nil, settings: nil, **extra)
+        body = {
+          'workspace_id' => workspace_id,
+          'status' => status,
+          'content' => normalize_content(content),
+          'accounts' => normalize_accounts(accounts)
+        }
+        body.merge!(
+          compact_nil(
+            'schedule_at' => iso8601(schedule_at),
+            'labels' => labels&.to_a,
+            'title' => title,
+            'summary' => summary,
+            'content_type' => content_type,
+            'settings' => settings
+          )
+        )
+        body.merge!(stringify(extra))
+
+        Post.new(unwrap(http.post('/posts', body)))
+      end
+
+      # Partial update — only the fields you pass are sent. Pass an explicit nil
+      # to clear a field.
+      def update(post_id, content: UNSET, accounts: UNSET, status: UNSET, schedule_at: UNSET,
+                 labels: UNSET, title: UNSET, summary: UNSET, content_type: UNSET,
+                 settings: UNSET, **extra)
+        body = compact_unset(
+          'content' => UNSET.equal?(content) ? UNSET : normalize_content(content),
+          'accounts' => UNSET.equal?(accounts) ? UNSET : normalize_accounts(accounts),
+          'status' => status,
+          'schedule_at' => UNSET.equal?(schedule_at) ? UNSET : iso8601(schedule_at),
+          'labels' => UNSET.equal?(labels) ? UNSET : labels&.to_a,
+          'title' => title,
+          'summary' => summary,
+          'content_type' => content_type,
+          'settings' => settings
+        )
+        body.merge!(stringify(extra))
+
+        Post.new(unwrap(http.put("/posts/#{post_id}", body)))
+      end
+
+      def delete(post_id)
+        http.delete("/posts/#{post_id}")
+        nil
+      end
+
+      # Queue the post for immediate delivery to its accounts.
+      def publish(post_id)
+        as_hash(unwrap(http.post("/posts/#{post_id}/publish")))
+      end
+
+      def cancel(post_id)
+        as_hash(unwrap(http.post("/posts/#{post_id}/cancel")))
+      end
+
+      # Retry the deliveries that failed, leaving the successful ones alone.
+      def retry(post_id)
+        as_hash(unwrap(http.post("/posts/#{post_id}/retry")))
+      end
+
+      # Per-account blockers and advisory content signals, without publishing.
+      def preflight(post_id)
+        as_hash(unwrap(http.post("/posts/#{post_id}/preflight")))
+      end
+
+      def deliveries(post_id)
+        parse_list(Delivery, unwrap(http.get("/posts/#{post_id}/deliveries")))
+      end
+
+      private
+
+      # Accept a bare string, one block, or an array of either.
+      def normalize_content(content)
+        blocks = content.is_a?(Array) ? content : [content]
+
+        blocks.map do |block|
+          case block
+          when String then { 'text' => block }
+          when ContentBlock
+            {
+              'text' => block.text,
+              'media' => block.media.map { |item| compact_nil(stringify(item.to_h)) }
+            }
+          when Hash then compact_nil(stringify(block))
+          else
+            raise ArgumentError, "fopost: cannot read a content block from #{block.inspect}"
+          end
+        end
+      end
+
+      # The API takes bare account ids; also accept account objects or {"id" => ...}.
+      def normalize_accounts(accounts)
+        Array(accounts).map do |account|
+          case account
+          when String then account
+          when SocialAccount then account.id
+          when Hash
+            id = account['id'] || account[:id]
+            raise ArgumentError, "fopost: cannot read an account id from #{account.inspect}" unless id.is_a?(String)
+
+            id
+          else
+            raise ArgumentError, "fopost: cannot read an account id from #{account.inspect}"
+          end
+        end
+      end
+
+      def stringify(hash)
+        hash.each_with_object({}) { |(key, value), out| out[key.to_s] = value }
+      end
+    end
+  end
+end