fopost-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5959178d911d67f15c611ae03d778c338acb8c90e0f0d40b5b6484ba5b0608c6
+  data.tar.gz: 4ed0650b489d85ad122a10ee30787456eca0606846c8bfcdab4aeb42ccf8fe23
+SHA512:
+  metadata.gz: dc18b76fcd3d73197793b2803bd7b427b86d8d9a4e194528c70009b47712841ff8317eeaecb957920506ddea4b9b7200afafe23588a178e7a4e93f997007ad34
+  data.tar.gz: f89fa93ca20e7f221a0e3e7fd90c18dfd9853a4e964b20bfe9ddfdc47a90831212e74232fa130976ca4c2f10610094afae7f8f27d9b76b6078b0cf695607ed8f

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this gem are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the gem follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-08-30
+
+Initial release.
+
+- `Fopost::Rails.configure` and `config.fopost`, resolving each setting from an explicit value,
+  then Rails credentials under `fopost:`, then the environment.
+- A memoized, thread-safe `Fopost::Rails.client`.
+- `rails generate fopost:install`, writing `config/initializers/fopost.rb`.
+- `PublishJob` and `CreatePostJob`, re-enqueueing a rate-limited call for the interval the API
+  asked for.
+- A mountable engine that verifies incoming webhook signatures and republishes them as
+  `ActiveSupport::Notifications` events.
+
+[0.1.0]: https://github.com/fopost/fopost-rails/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Porter Bridge, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,233 @@
+# FoPost for Rails
+
+[![Gem Version](https://img.shields.io/gem/v/fopost-rails.svg)](https://rubygems.org/gems/fopost-rails)
+[![Downloads](https://img.shields.io/gem/dt/fopost-rails.svg)](https://rubygems.org/gems/fopost-rails)
+[![CI](https://img.shields.io/github/actions/workflow/status/fopost/fopost-rails/ci.yml?branch=main&label=ci)](https://github.com/fopost/fopost-rails/actions)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+The official Rails integration for the [FoPost](https://fopost.com) API. Connect social accounts
+once, then compose, schedule, and publish to +30 platforms from your own application.
+
+This gem is a thin wrapper around the [`fopost`](https://github.com/fopost/fopost-ruby) gem. Every
+request, retry, model, and error class lives there; what is added here is Rails wiring:
+
+- `config.fopost` and Rails credentials, with a sensible fallback order
+- a memoized, thread-safe `Fopost::Rails.client`
+- `rails generate fopost:install`
+- ActiveJob jobs, so publishing never blocks a request
+- a mountable endpoint that verifies and republishes incoming FoPost webhooks
+
+Requires Ruby 3.1+ and Rails 7.0+.
+
+> **0.x release.** The public API is still settling and minor versions may contain breaking
+> changes. Pin an exact version if that matters to you.
+
+## Install
+
+```bash
+bundle add fopost-rails
+```
+
+Then write the initializer:
+
+```bash
+bin/rails generate fopost:install
+```
+
+## Configure
+
+Create an API key at [app.fopost.com/api-keys](https://app.fopost.com/api-keys) and put it
+somewhere the app can read it:
+
+```bash
+bin/rails credentials:edit
+```
+
+```yaml
+fopost:
+  api_key: fp_your_key_here
+  default_workspace_id: ws_...
+  webhook_secret: whsec_...
+```
+
+Or in the environment:
+
+```dotenv
+FOPOST_API_KEY=fp_your_key_here
+```
+
+Every setting resolves the same way — **what you set explicitly wins, then Rails credentials under
+`fopost:`, then the environment, then the default**:
+
+| Setting | Credentials key | Environment | Default |
+| --- | --- | --- | --- |
+| `api_key` | `fopost: api_key:` | `FOPOST_API_KEY` | none, required |
+| `base_url` | `base_url` | `FOPOST_BASE_URL` | `https://api.fopost.com/v1` |
+| `timeout` | `timeout` | `FOPOST_TIMEOUT` | `30.0` |
+| `max_retries` | `max_retries` | `FOPOST_MAX_RETRIES` | `3` |
+| `default_workspace_id` | `default_workspace_id` | `FOPOST_WORKSPACE_ID` | none |
+| `webhook_secret` | `webhook_secret` | `FOPOST_WEBHOOK_SECRET` | none |
+| `queue_name` | `queue_name` | `FOPOST_QUEUE` | `default` |
+
+Set them in the initializer:
+
+```ruby
+Fopost::Rails.configure do |config|
+  config.api_key = Rails.application.credentials.dig(:fopost, :api_key)
+  config.queue_name = 'social'
+end
+```
+
+or from `config/application.rb`:
+
+```ruby
+config.fopost.default_workspace_id = 'ws_...'
+```
+
+## Publishing from a controller
+
+`Fopost::Rails.client` is a configured `Fopost::Client`, memoized and safe to call from any
+thread. The [`fopost` gem README](https://github.com/fopost/fopost-ruby) documents the full
+resource surface — `posts`, `accounts`, `workspaces`, `labels`, `ai`.
+
+```ruby
+class PostsController < ApplicationController
+  def index
+    @posts = Fopost::Rails.client.posts.list(status: 'scheduled')
+  end
+
+  def create
+    post = Fopost::Rails.client.posts.create(
+      workspace_id: Fopost::Rails.config.default_workspace_id,
+      content: params.require(:text),
+      accounts: params.require(:account_ids)
+    )
+
+    Fopost::Rails::PublishJob.perform_later(post.id)
+    redirect_to posts_path, notice: 'Queued for publishing.'
+  end
+end
+```
+
+Errors are the SDK's, so one `rescue_from` covers the lot:
+
+```ruby
+rescue_from Fopost::PaymentRequiredError do |error|
+  redirect_to error.upgrade_url, alert: error.message
+end
+
+rescue_from Fopost::Error do |error|
+  Rails.logger.error("FoPost: #{error}")   # "[404 (not_found)] Post not found"
+  head :bad_gateway
+end
+```
+
+## Background jobs
+
+Publishing reaches a third-party network, so it belongs off the request cycle.
+
+```ruby
+# Publish something that already exists.
+Fopost::Rails::PublishJob.perform_later(post.id)
+
+# Compose and, optionally, send in one job.
+Fopost::Rails::CreatePostJob.perform_later(
+  content: 'Shipping today.',
+  accounts: account_ids,
+  publish: true
+)
+
+# Or schedule it, and pass anything else the SDK takes through `options`.
+Fopost::Rails::CreatePostJob.perform_later(
+  workspace_id: 'ws_...',
+  content: ['First post in the thread', 'And the reply'],
+  accounts: account_ids,
+  status: 'scheduled',
+  schedule_at: 1.hour.from_now,
+  options: { labels: ['launch'], title: 'Launch week' }
+)
+```
+
+`workspace_id` falls back to `config.default_workspace_id`. Both jobs run on `config.queue_name`.
+
+When the API answers `429`, the job is re-enqueued for exactly the interval the API asked for in
+`Retry-After` (capped at a minute), up to five attempts. Every other `Fopost::Error` is left to
+your queue's own error handling.
+
+Publishing returns once delivery is **queued**, not once it is live. Subscribe to
+`fopost.post.published` for that.
+
+## Receiving webhooks
+
+Mount the engine:
+
+```ruby
+# config/routes.rb
+mount Fopost::Rails::Engine => '/fopost'
+```
+
+That serves `POST /fopost/webhooks`. Create a webhook pointing at it, copy the secret it shows you
+once into `config.webhook_secret`, and subscribe:
+
+```ruby
+# config/initializers/fopost_webhooks.rb
+ActiveSupport::Notifications.subscribe('fopost.post.published') do |*, payload|
+  payload[:event]        # "post.published"
+  payload[:data]         # the event body FoPost sent
+  payload[:timestamp]    # ISO 8601, when FoPost sent it
+  payload[:delivery_id]  # X-FoPost-Delivery, unique per attempt
+  payload[:payload]      # the whole parsed body
+end
+```
+
+Two notifications fire per verified delivery: `fopost.<event>` and `fopost.webhook` for a
+catch-all. The events FoPost sends are `post.published`, `post.failed`, `post.partially_failed`,
+`delivery.published`, `delivery.failed`, `delivery.delayed`, and `account.health_changed`.
+
+Verification is not optional and not yours to write. FoPost signs the exact bytes of the request
+body with HMAC-SHA256, keyed by the webhook secret, and sends the hex digest as
+`X-FoPost-Signature: sha256=<digest>`. The controller recomputes it over the raw body and compares
+in constant time; a mismatch is a `401` and publishes nothing, and an unconfigured secret is a
+`503` rather than a pretended success.
+
+To sign a request yourself — in a request spec, say:
+
+```ruby
+body = { event: 'post.published', data: { postId: 'post_1' } }.to_json
+
+post '/fopost/webhooks',
+     params: body,
+     headers: {
+       'CONTENT_TYPE' => 'application/json',
+       'X-FoPost-Signature' => Fopost::Rails::WebhookSignature.sign(body, secret)
+     }
+```
+
+## Testing your app
+
+Swap the client for one wired to your own transport and nothing touches the network:
+
+```ruby
+Fopost::Rails.client = Fopost::Client.new(api_key: 'fp_test', transport: my_stub)
+```
+
+`Fopost::Rails.reset!` puts config and client back to their defaults between tests.
+
+## Looking for the free self-hosted toolkit?
+
+This gem talks to the FoPost Cloud API with a FoPost API key. To publish straight to the social
+platforms using your own app credentials, with no FoPost account involved, use
+[`fopost-social-core`](https://github.com/fopost/fopost-social-core) instead. The two families are
+separate on purpose and never depend on each other.
+
+## Links
+
+- Documentation: [fopost.com/docs](https://fopost.com/docs)
+- API keys: [app.fopost.com/api-keys](https://app.fopost.com/api-keys)
+- The SDK this wraps: [`fopost`](https://github.com/fopost/fopost-ruby)
+- Issues: [github.com/fopost/fopost-rails/issues](https://github.com/fopost/fopost-rails/issues)
+- Support: [fopost.com/contact](https://fopost.com/contact)
+
+## License
+
+MIT. Copyright (c) 2026 Porter Bridge, LLC. See [LICENSE](LICENSE).

data/app/controllers/fopost/rails/webhooks_controller.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'active_support/notifications'
+require 'fopost/rails/webhook_signature'
+
+module Fopost
+  module Rails
+    # Receives FoPost webhooks and republishes them as
+    # ActiveSupport::Notifications events, so subscribing costs no route,
+    # controller, or queue of your own.
+    #
+    #   ActiveSupport::Notifications.subscribe('fopost.post.published') do |*, payload|
+    #     Rails.logger.info(payload[:data])
+    #   end
+    #
+    # Two events fire per delivery: `fopost.<event>` (`fopost.post.published`,
+    # `fopost.delivery.failed`, …) and `fopost.webhook` for a catch-all.
+    class WebhooksController < ActionController::API
+      def create
+        secret = Fopost::Rails.config.webhook_secret
+        return head :service_unavailable if secret.nil? || secret.to_s.empty?
+
+        payload = request.raw_post
+        signature = request.headers[WebhookSignature::SIGNATURE_HEADER]
+        return head :unauthorized unless WebhookSignature.valid?(payload, signature, secret)
+
+        body = parse(payload)
+        event = body && body['event']
+        return head :bad_request unless event.is_a?(String) && !event.empty?
+
+        publish(event, body)
+        head :ok
+      end
+
+      private
+
+      def publish(event, body)
+        notification = {
+          event: event,
+          data: body['data'],
+          timestamp: body['timestamp'],
+          delivery_id: request.headers[WebhookSignature::DELIVERY_HEADER],
+          payload: body
+        }
+
+        ActiveSupport::Notifications.instrument("fopost.#{event}", notification)
+        ActiveSupport::Notifications.instrument('fopost.webhook', notification)
+      end
+
+      def parse(payload)
+        parsed = JSON.parse(payload.to_s)
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+Fopost::Rails::Engine.routes.draw do
+  post '/webhooks', to: 'webhooks#create', as: :webhooks
+
+  # So mounting straight onto the endpoint path also works:
+  #   mount Fopost::Rails::Engine => '/fopost/webhooks'
+  post '/', to: 'webhooks#create', as: :root
+end

data/lib/fopost/rails/application_job.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'active_job'
+require 'fopost/rails'
+
+module Fopost
+  module Rails
+    # Base for the jobs this gem ships.
+    #
+    # A rate-limited call is re-enqueued for exactly as long as the API asked
+    # for in `Retry-After`, instead of a guessed backoff.
+    class ApplicationJob < ActiveJob::Base
+      # The API never asks for longer than a minute; ignore it if it does.
+      MAX_RETRY_WAIT = 60
+
+      # ActiveJob hands the `wait:` proc the attempt count and nothing else, so
+      # the seconds the API asked for ride along on the thread that raised.
+      # `rescue_from` runs on that same thread, right after `perform`.
+      RETRY_AFTER_KEY = :fopost_rails_retry_after
+
+      queue_as { Fopost::Rails.config.queue_name }
+
+      retry_on Fopost::RateLimitError,
+               attempts: 5,
+               wait: lambda { |executions|
+                 asked = Thread.current[RETRY_AFTER_KEY]
+                 Thread.current[RETRY_AFTER_KEY] = nil
+                 seconds = asked.to_f
+                 seconds.positive? ? [seconds, MAX_RETRY_WAIT].min.ceil : 2**executions
+               }
+
+      private
+
+      def client
+        Fopost::Rails.client
+      end
+
+      # Wrap every API call, so a 429 carries its interval into the retry.
+      def with_retry_after
+        yield
+      rescue Fopost::RateLimitError => e
+        Thread.current[RETRY_AFTER_KEY] = e.retry_after
+        raise
+      end
+    end
+  end
+end

data/lib/fopost/rails/configuration.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'fopost'
+
+module Fopost
+  module Rails
+    # Settings for the API client, the jobs, and the webhook endpoint.
+    #
+    # Every setting resolves the same way: what you set explicitly wins, then
+    # Rails credentials under `fopost:`, then the environment, then a default.
+    #
+    #   Fopost::Rails.configure do |config|
+    #     config.api_key = 'fp_...'
+    #     config.default_workspace_id = 'ws_...'
+    #   end
+    class Configuration
+      SETTINGS = %i[
+        api_key base_url timeout max_retries default_workspace_id webhook_secret queue_name
+      ].freeze
+
+      ENV_KEYS = {
+        api_key: 'FOPOST_API_KEY',
+        base_url: 'FOPOST_BASE_URL',
+        timeout: 'FOPOST_TIMEOUT',
+        max_retries: 'FOPOST_MAX_RETRIES',
+        default_workspace_id: 'FOPOST_WORKSPACE_ID',
+        webhook_secret: 'FOPOST_WEBHOOK_SECRET',
+        queue_name: 'FOPOST_QUEUE'
+      }.freeze
+
+      DEFAULTS = {
+        base_url: Fopost::Client::DEFAULT_BASE_URL,
+        timeout: 30.0,
+        max_retries: 3,
+        queue_name: 'default'
+      }.freeze
+
+      attr_writer(*SETTINGS)
+
+      def api_key
+        resolve(:api_key)
+      end
+
+      def base_url
+        resolve(:base_url)
+      end
+
+      def timeout
+        value = resolve(:timeout)
+        value&.to_f
+      end
+
+      def max_retries
+        value = resolve(:max_retries)
+        value&.to_i
+      end
+
+      def default_workspace_id
+        resolve(:default_workspace_id)
+      end
+
+      # Shown once, when the webhook is created. The mounted endpoint needs it
+      # to verify the signature FoPost sends.
+      def webhook_secret
+        resolve(:webhook_secret)
+      end
+
+      def queue_name
+        resolve(:queue_name)
+      end
+
+      # The `fopost:` section of Rails credentials, or an empty hash outside a
+      # booted app. A missing master key is treated as "no credentials" rather
+      # than an error, so a machine without the key still boots.
+      def credentials
+        app = defined?(::Rails) && ::Rails.respond_to?(:application) ? ::Rails.application : nil
+        section = app&.credentials&.fopost
+        section.respond_to?(:[]) ? section : {}
+      rescue StandardError
+        {}
+      end
+
+      # Drop every explicit value, so the next read falls back again.
+      def reset!
+        SETTINGS.each { |key| instance_variable_set(:"@#{key}", nil) }
+        self
+      end
+
+      def to_h
+        SETTINGS.to_h { |key| [key, public_send(key)] }
+      end
+
+      # Keeps the key out of logs and consoles.
+      def inspect
+        redacted = to_h.merge(api_key: mask(api_key), webhook_secret: mask(webhook_secret))
+        "#<Fopost::Rails::Configuration #{redacted.map { |k, v| "#{k}=#{v.inspect}" }.join(' ')}>"
+      end
+
+      private
+
+      def resolve(key)
+        explicit = instance_variable_get(:"@#{key}")
+        return explicit unless explicit.nil?
+
+        from_credentials = credentials[key]
+        return from_credentials unless from_credentials.nil?
+
+        from_env = ENV[ENV_KEYS.fetch(key)]
+        return from_env unless from_env.nil? || from_env.empty?
+
+        DEFAULTS[key]
+      end
+
+      def mask(value)
+        value.nil? || value.empty? ? value : "#{value[0, 4]}…"
+      end
+    end
+  end
+end

data/lib/fopost/rails/create_post_job.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'fopost/rails/application_job'
+
+module Fopost
+  module Rails
+    # Create a post — and optionally send it — off the request cycle.
+    #
+    #   Fopost::Rails::CreatePostJob.perform_later(
+    #     content: 'Shipping today.',
+    #     accounts: account_ids,
+    #     publish: true
+    #   )
+    #
+    # `workspace_id` falls back to `config.default_workspace_id`. `options` is
+    # merged into the create call, so anything the SDK takes (`labels`,
+    # `title`, `settings`, …) passes straight through.
+    class CreatePostJob < ApplicationJob
+      def perform(content:, accounts:, workspace_id: nil, status: 'draft', schedule_at: nil,
+                  publish: false, options: {})
+        workspace = workspace_id || Fopost::Rails.config.default_workspace_id
+        if workspace.nil? || workspace.to_s.empty?
+          raise ArgumentError,
+                'fopost: pass workspace_id: or set config.default_workspace_id'
+        end
+
+        post = with_retry_after do
+          client.posts.create(
+            workspace_id: workspace,
+            content: content,
+            accounts: accounts,
+            status: status,
+            schedule_at: schedule_at,
+            **(options || {}).transform_keys(&:to_sym)
+          )
+        end
+
+        with_retry_after { client.posts.publish(post.id) } if publish
+
+        post.id
+      end
+    end
+  end
+end

data/lib/fopost/rails/engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'rails/engine'
+
+module Fopost
+  module Rails
+    # Mount to receive FoPost webhooks:
+    #
+    #   # config/routes.rb
+    #   mount Fopost::Rails::Engine => '/fopost'
+    #
+    # That serves `POST /fopost/webhooks`. Point a webhook at it, set
+    # `config.webhook_secret` to the secret FoPost showed you once, and
+    # subscribe to the events it publishes.
+    class Engine < ::Rails::Engine
+      isolate_namespace Fopost::Rails
+    end
+  end
+end

data/lib/fopost/rails/publish_job.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'fopost/rails/application_job'
+
+module Fopost
+  module Rails
+    # Publish an existing post without blocking the request that asked for it.
+    #
+    #   Fopost::Rails::PublishJob.perform_later(post_id)
+    #
+    # Returns once the API has queued delivery, which is not the same as live:
+    # subscribe to `fopost.post.published` for that.
+    class PublishJob < ApplicationJob
+      def perform(post_id)
+        with_retry_after { client.posts.publish(post_id) }
+      end
+    end
+  end
+end

data/lib/fopost/rails/railtie.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module Fopost
+  module Rails
+    # Registers `config.fopost`, so an app can set the SDK up from
+    # `config/application.rb`:
+    #
+    #   config.fopost.api_key = Rails.application.credentials.dig(:fopost, :api_key)
+    #
+    # Nothing is loaded eagerly: the client is built on first use and the jobs
+    # are autoloaded, so booting this gem costs a require of the SDK.
+    class Railtie < ::Rails::Railtie
+      config.fopost = Fopost::Rails.config
+
+      # An initializer may have written settings after something already built a
+      # client, so drop it once boot is done.
+      config.after_initialize { Fopost::Rails.reset_client! }
+    end
+  end
+end

data/lib/fopost/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Fopost
+  module Rails
+    VERSION = '0.1.0'
+  end
+end

data/lib/fopost/rails/webhook_signature.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'active_support/security_utils'
+
+module Fopost
+  module Rails
+    # FoPost signs every webhook body with HMAC-SHA256 over the exact bytes it
+    # sent, keyed by the webhook secret, and puts the hex digest in
+    # `X-FoPost-Signature` behind a `sha256=` prefix.
+    #
+    # Verify against the raw request body — a parsed-and-re-serialized hash will
+    # not match.
+    module WebhookSignature
+      SIGNATURE_HEADER = 'X-FoPost-Signature'
+      EVENT_HEADER = 'X-FoPost-Event'
+      DELIVERY_HEADER = 'X-FoPost-Delivery'
+      PREFIX = 'sha256='
+
+      # The header value FoPost would send for this body and secret.
+      def self.sign(payload, secret)
+        "#{PREFIX}#{OpenSSL::HMAC.hexdigest('SHA256', secret.to_s, payload.to_s)}"
+      end
+
+      # Constant-time comparison, so a wrong signature leaks no timing.
+      def self.valid?(payload, signature, secret)
+        return false if signature.nil? || secret.nil? || secret.to_s.empty?
+
+        ActiveSupport::SecurityUtils.secure_compare(sign(payload, secret), signature.to_s)
+      end
+    end
+  end
+end

data/lib/fopost/rails.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'fopost'
+
+require 'fopost/rails/version'
+require 'fopost/rails/configuration'
+
+# Official Rails integration for the FoPost API.
+#
+# This gem is a thin wrapper: every request, retry, model, and error class
+# lives in the `fopost` gem. What is added here is Rails wiring — configuration
+# and credentials, a memoized client, an install generator, ActiveJob jobs, and
+# a mountable endpoint for receiving webhooks.
+#
+#   Fopost::Rails.client.posts.list(status: 'scheduled')
+#   Fopost::Rails::PublishJob.perform_later(post.id)
+module Fopost
+  module Rails
+    # Loaded on first use, so an app that never enqueues a job never pulls
+    # ActiveJob in on our account, and requiring this gem stays cheap.
+    autoload :ApplicationJob, 'fopost/rails/application_job'
+    autoload :CreatePostJob, 'fopost/rails/create_post_job'
+    autoload :PublishJob, 'fopost/rails/publish_job'
+    autoload :WebhookSignature, 'fopost/rails/webhook_signature'
+
+    @mutex = Mutex.new
+    @client = nil
+    @config = nil
+
+    class << self
+      # The settings object. Also reachable as `config.fopost` inside
+      # `config/application.rb` and any Rails initializer.
+      def config
+        @config ||= Configuration.new
+      end
+      alias configuration config
+
+      #   Fopost::Rails.configure do |c|
+      #     c.api_key = ENV['FOPOST_API_KEY']
+      #   end
+      def configure
+        yield config
+        reset_client!
+        config
+      end
+
+      # A memoized, configured Fopost::Client. Safe to call from any thread.
+      def client
+        @client || @mutex.synchronize { @client ||= build_client }
+      end
+
+      # Swap in your own client — a stubbed transport in tests, say.
+      def client=(client)
+        @mutex.synchronize { @client = client }
+      end
+
+      # Forget the memoized client, so the next call rebuilds it from config.
+      def reset_client!
+        @mutex.synchronize { @client = nil }
+        nil
+      end
+
+      # Config and client back to their defaults. Meant for test suites.
+      def reset!
+        reset_client!
+        config.reset!
+        nil
+      end
+
+      private
+
+      def build_client
+        Fopost::Client.new(
+          api_key: config.api_key,
+          base_url: config.base_url,
+          timeout: config.timeout,
+          max_retries: config.max_retries
+        )
+      end
+    end
+  end
+end
+
+require 'fopost/rails/railtie' if defined?(::Rails::Railtie)
+require 'fopost/rails/engine' if defined?(::Rails::Engine)

data/lib/fopost-rails.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Lets `require 'fopost-rails'` work, matching the gem name.
+require 'fopost/rails'

data/lib/generators/fopost/install/install_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module Fopost
+  module Generators
+    # `rails generate fopost:install`
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Writes config/initializers/fopost.rb.'
+
+      def copy_initializer
+        template 'fopost.rb.tt', 'config/initializers/fopost.rb'
+      end
+
+      def print_next_steps
+        say <<~TEXT
+
+          Next: put your API key somewhere the app can read it.
+
+            bin/rails credentials:edit     # fopost: { api_key: fp_... }
+            # or export FOPOST_API_KEY=fp_...
+
+          Create a key at https://app.fopost.com/api-keys.
+        TEXT
+      end
+    end
+  end
+end

data/lib/generators/fopost/install/templates/fopost.rb.tt

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# FoPost — https://fopost.com/docs
+#
+# Every setting below falls back on its own, in this order: what you set here,
+# then Rails credentials under `fopost:`, then the environment. Leave a line
+# commented to take the fallback.
+Fopost::Rails.configure do |config|
+  # Create a key at https://app.fopost.com/api-keys.
+  # Falls back to credentials `fopost: api_key:`, then ENV['FOPOST_API_KEY'].
+  # config.api_key = nil
+
+  # config.base_url = 'https://api.fopost.com/v1'
+  # config.timeout = 30.0
+  # config.max_retries = 3
+
+  # Used by CreatePostJob when no workspace is passed.
+  # config.default_workspace_id = nil
+
+  # Shown once, when you create a webhook. Required by the mounted endpoint.
+  # config.webhook_secret = nil
+
+  # ActiveJob queue for PublishJob and CreatePostJob.
+  # config.queue_name = 'default'
+end
+
+# To receive webhooks, mount the engine in config/routes.rb:
+#
+#   mount Fopost::Rails::Engine => '/fopost'
+#
+# then point a webhook at https://your-app.example/fopost/webhooks and subscribe:
+#
+#   ActiveSupport::Notifications.subscribe('fopost.post.published') do |*, payload|
+#     Rails.logger.info("FoPost published: #{payload[:data]}")
+#   end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: fopost-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- FoPost
+- Porter Bridge, LLC
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: fopost
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: 'Rails integration for the FoPost API: configuration and credentials,
+  a memoized client, ActiveJob jobs, and a mountable webhook endpoint. A thin wrapper
+  around the fopost gem.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/controllers/fopost/rails/webhooks_controller.rb
+- config/routes.rb
+- lib/fopost-rails.rb
+- lib/fopost/rails.rb
+- lib/fopost/rails/application_job.rb
+- lib/fopost/rails/configuration.rb
+- lib/fopost/rails/create_post_job.rb
+- lib/fopost/rails/engine.rb
+- lib/fopost/rails/publish_job.rb
+- lib/fopost/rails/railtie.rb
+- lib/fopost/rails/version.rb
+- lib/fopost/rails/webhook_signature.rb
+- lib/generators/fopost/install/install_generator.rb
+- lib/generators/fopost/install/templates/fopost.rb.tt
+homepage: https://fopost.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://fopost.com
+  source_code_uri: https://github.com/fopost/fopost-rails
+  bug_tracker_uri: https://github.com/fopost/fopost-rails/issues
+  documentation_uri: https://fopost.com/docs
+  changelog_uri: https://github.com/fopost/fopost-rails/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Rails integration for the FoPost API.
+test_files: []