parcelwing 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d1b3ca45dc11f64e6621fe16e1b2cd9cc71db8678a21ee2ec1aea59f54d81df1
+  data.tar.gz: 5e275098ddd05f093167b1baba93d8d6de546c66528f69fabd7443e270851246
+SHA512:
+  metadata.gz: cb471826a1e01804e195d7a0a195ea821c290a815c4500134f69cd4339be945a0712c57ff19b4652b8da760437fefe0f7a88680f2cf416594bbd6ab8f2aa58aa
+  data.tar.gz: ca50220fdb5063b3ba69e325e579a1db68f5caf30f43b3c5ef7bca7240cf2dac494d0515180a7f26a498c9fb75a8446d23741e140fdeb74ea2356c1199405571

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parcel Wing
+
+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,209 @@
+# Parcel Wing Ruby SDK
+
+Official Ruby SDK for the [Parcel Wing](https://parcelwing.com) API.
+
+```bash
+gem install parcelwing
+```
+
+Or add it to your `Gemfile`:
+
+```ruby
+gem "parcelwing"
+```
+
+## Requirements
+
+- Ruby 3.0+
+- A Parcel Wing API key
+- A verified sending domain in Parcel Wing
+
+## Send an email
+
+```ruby
+require "parcelwing"
+
+parcelwing = ParcelWing::Client.new(api_key: "pw_live_your_api_key_here")
+
+emails = parcelwing.emails.send(
+  from: "Parcel Wing <hello@yourdomain.com>",
+  to: "you@example.com",
+  subject: "Hello from Parcel Wing",
+  html: "<strong>It works!</strong>",
+  text: "It works!"
+)
+
+puts emails
+```
+
+`emails.send` returns an array of queued email objects:
+
+```ruby
+[
+  {
+    "object" => "email",
+    "id" => "...",
+    "to" => "you@example.com",
+    "status" => "queued"
+  }
+]
+```
+
+## Configuration
+
+```ruby
+parcelwing = ParcelWing::Client.new(
+  api_key: ENV.fetch("PARCELWING_API_KEY"),
+  base_url: ENV.fetch("PARCELWING_BASE_URL", "https://parcelwing.com"),
+  timeout: 30,
+  headers: {
+    "X-My-App" => "my-ruby-app"
+  }
+)
+```
+
+## Emails
+
+```ruby
+parcelwing.emails.send(
+  from: "Parcel Wing <hello@yourdomain.com>",
+  to: ["alice@example.com", "bob@example.com"],
+  subject: "Hello from Parcel Wing",
+  text: "Plain text body",
+  html: "<p>HTML body</p>",
+  reply_to: "support@yourdomain.com",
+  tags: {
+    campaign: "welcome"
+  }
+)
+```
+
+You can also send using a stored template:
+
+```ruby
+parcelwing.emails.send(
+  from: "Parcel Wing <hello@yourdomain.com>",
+  to: "you@example.com",
+  template_alias: "welcome",
+  template_params: {
+    first_name: "Ada"
+  }
+)
+```
+
+## Contacts
+
+```ruby
+contact = parcelwing.contacts.create(
+  email: "ada@example.com",
+  first_name: "Ada",
+  last_name: "Lovelace",
+  attributes: {
+    plan: "flight"
+  }
+)
+
+contacts = parcelwing.contacts.list(limit: 25, status: "active")
+contact = parcelwing.contacts.get(contact.fetch("id"))
+updated = parcelwing.contacts.update(contact.fetch("id"), first_name: "Augusta")
+parcelwing.contacts.delete(contact.fetch("id"))
+```
+
+Batch create contacts by passing an array:
+
+```ruby
+result = parcelwing.contacts.create([
+  { email: "alice@example.com" },
+  { email: "bob@example.com" }
+])
+```
+
+## Segments
+
+```ruby
+segment = parcelwing.segments.create(
+  name: "Active customers",
+  filter_criteria: {
+    version: 1,
+    match: "all",
+    conditions: [
+      {
+        field: "status",
+        operator: "equals",
+        value: "active"
+      }
+    ]
+  }
+)
+
+segments = parcelwing.segments.list(include_counts: true)
+segment = parcelwing.segments.get(segment.fetch("id"))
+parcelwing.segments.update(segment.fetch("id"), name: "Active subscribers")
+parcelwing.segments.delete(segment.fetch("id"))
+```
+
+## Topics
+
+```ruby
+topic = parcelwing.topics.create(
+  name: "Product updates",
+  description: "News and feature announcements",
+  default_subscription: "opt_in",
+  visibility: "public"
+)
+
+topics = parcelwing.topics.list(active: true)
+topic = parcelwing.topics.get(topic.fetch("id"))
+parcelwing.topics.update(topic.fetch("id"), description: "Product news")
+parcelwing.topics.delete(topic.fetch("id"))
+```
+
+## Automations
+
+```ruby
+event = parcelwing.automations.track(
+  event_name: "signup_completed",
+  contact_id: "contact-id",
+  payload: {
+    plan: "launch"
+  },
+  event_id: "signup-123"
+)
+```
+
+## Error handling
+
+API and transport errors raise `ParcelWing::Error`.
+
+```ruby
+begin
+  parcelwing.emails.send(
+    from: "Parcel Wing <hello@yourdomain.com>",
+    to: "you@example.com",
+    subject: "Hello",
+    text: "Hello!"
+  )
+rescue ParcelWing::Error => e
+  warn "Parcel Wing error: #{e.message}"
+  warn "status=#{e.status} type=#{e.type} code=#{e.code} request_id=#{e.request_id}"
+end
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+Build the gem locally:
+
+```bash
+gem build parcelwing.gemspec
+```
+
+Install the local build:
+
+```bash
+gem install ./parcelwing-0.1.0.gem
+```

data/examples/send_email.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "parcelwing"
+
+client = ParcelWing::Client.new(
+  api_key: ENV.fetch("PARCELWING_API_KEY"),
+  base_url: ENV.fetch("PARCELWING_BASE_URL", "https://parcelwing.com")
+)
+
+emails = client.emails.send(
+  from: "Parcel Wing <hello@yourdomain.com>",
+  to: "you@example.com",
+  subject: "Hello from Parcel Wing",
+  html: "<strong>It works!</strong>",
+  text: "It works!"
+)
+
+puts emails.inspect

data/lib/parcelwing/client.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "http_client"
+require_relative "resources/emails"
+require_relative "resources/contacts"
+require_relative "resources/segments"
+require_relative "resources/topics"
+require_relative "resources/automations"
+
+module ParcelWing
+  class Client
+    attr_reader :emails, :contacts, :segments, :topics, :automations, :http
+
+    def initialize(api_key:, base_url: HttpClient::DEFAULT_BASE_URL, timeout: HttpClient::DEFAULT_TIMEOUT, headers: {}, transport: nil)
+      @http = HttpClient.new(
+        api_key: api_key,
+        base_url: base_url,
+        timeout: timeout,
+        headers: headers,
+        transport: transport
+      )
+
+      @emails = Resources::Emails.new(@http)
+      @contacts = Resources::Contacts.new(@http)
+      @segments = Resources::Segments.new(@http)
+      @topics = Resources::Topics.new(@http)
+      @automations = Resources::Automations.new(@http)
+    end
+  end
+end

data/lib/parcelwing/error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ParcelWing
+  class Error < StandardError
+    attr_reader :status, :type, :code, :request_id, :details, :metadata
+
+    def initialize(message:, status:, type: "api_error", code: nil, request_id: nil, details: nil, metadata: {})
+      super(message)
+      @status = status
+      @type = type
+      @code = code
+      @request_id = request_id
+      @details = details
+      @metadata = metadata || {}
+    end
+  end
+end

data/lib/parcelwing/http_client.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "cgi"
+require_relative "error"
+require_relative "version"
+
+module ParcelWing
+  class HttpClient
+    DEFAULT_BASE_URL = "https://parcelwing.com"
+    DEFAULT_TIMEOUT = 30
+
+    attr_reader :api_key, :base_url, :timeout, :headers
+
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, headers: {}, transport: nil)
+      raise ArgumentError, "ParcelWing client requires a non-empty api_key." if api_key.to_s.strip.empty?
+
+      @api_key = api_key.to_s.strip
+      @base_url = base_url.to_s.sub(%r{/+\z}, "")
+      @timeout = timeout
+      @headers = headers || {}
+      @transport = transport
+    end
+
+    def request(method:, path:, body: nil, query: nil, headers: {})
+      url = build_url(path, query)
+      request_headers = default_headers.merge(@headers).merge(headers || {})
+      encoded_body = nil
+
+      unless body.nil?
+        request_headers["Content-Type"] = "application/json"
+        encoded_body = JSON.generate(body)
+      end
+
+      response = perform_request(method: method, url: url, headers: request_headers, body: encoded_body)
+      parsed = parse_json(response[:body])
+
+      raise build_error(response[:status], parsed, response[:body]) unless response[:status].between?(200, 299)
+
+      parsed
+    rescue Error
+      raise
+    rescue Net::OpenTimeout, Net::ReadTimeout
+      raise Error.new(
+        status: 408,
+        type: "api_error",
+        code: "request_timeout",
+        message: "Request timed out after #{@timeout}s."
+      )
+    rescue StandardError => e
+      raise Error.new(
+        status: 0,
+        type: "api_error",
+        code: "network_error",
+        message: e.message
+      )
+    end
+
+    private
+
+    def default_headers
+      {
+        "Accept" => "application/json",
+        "Authorization" => "Bearer #{@api_key}",
+        "User-Agent" => "parcelwing-ruby/#{ParcelWing::VERSION}",
+        "X-ParcelWing-SDK" => "ruby/#{ParcelWing::VERSION}"
+      }
+    end
+
+    def build_url(path, query)
+      uri = URI.parse("#{@base_url}#{path}")
+      encoded_query = encode_query(query || {})
+      uri.query = encoded_query unless encoded_query.empty?
+      uri
+    end
+
+    def encode_query(params)
+      params.each_with_object([]) do |(key, value), pairs|
+        next if value.nil?
+
+        if value.is_a?(Array)
+          value.each { |entry| pairs << [key, entry] unless entry.nil? }
+        else
+          pairs << [key, value]
+        end
+      end.map do |key, value|
+        "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
+      end.join("&")
+    end
+
+    def perform_request(method:, url:, headers:, body:)
+      return normalize_transport_response(@transport.call(method: method, url: url, headers: headers, body: body, timeout: @timeout)) if @transport
+
+      http = Net::HTTP.new(url.host, url.port)
+      http.use_ssl = url.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      request_class = case method.to_s.upcase
+                      when "GET" then Net::HTTP::Get
+                      when "POST" then Net::HTTP::Post
+                      when "PATCH" then Net::HTTP::Patch
+                      when "DELETE" then Net::HTTP::Delete
+                      else
+                        raise ArgumentError, "Unsupported HTTP method: #{method}"
+                      end
+
+      request = request_class.new(url)
+      headers.each { |key, value| request[key] = value }
+      request.body = body if body
+
+      response = http.request(request)
+      { status: response.code.to_i, body: response.body.to_s, headers: response.to_hash }
+    end
+
+    def normalize_transport_response(response)
+      if response.is_a?(Hash)
+        return {
+          status: response.fetch(:status).to_i,
+          body: response.fetch(:body, "").to_s,
+          headers: response.fetch(:headers, {}) || {}
+        }
+      end
+
+      {
+        status: response.status.to_i,
+        body: response.body.to_s,
+        headers: response.respond_to?(:headers) ? response.headers : {}
+      }
+    end
+
+    def parse_json(body)
+      return nil if body.to_s.strip.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def build_error(status, parsed, fallback_body)
+      error = parsed.is_a?(Hash) ? parsed["error"] : nil
+
+      unless error.is_a?(Hash)
+        return Error.new(
+          status: status,
+          type: "api_error",
+          code: "http_error",
+          message: fallback_body.to_s.empty? ? "Parcel Wing API request failed with status #{status}." : fallback_body.to_s
+        )
+      end
+
+      metadata = error.dup
+      message = metadata.delete("message") || "Parcel Wing API request failed with status #{status}."
+      type = metadata.delete("type") || "api_error"
+      code = metadata.delete("code")
+      request_id = metadata.delete("request_id")
+      details = metadata.delete("details")
+
+      Error.new(
+        status: status,
+        type: type,
+        code: code,
+        request_id: request_id,
+        details: details,
+        metadata: metadata,
+        message: message
+      )
+    end
+  end
+end

data/lib/parcelwing/resources/automations.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ParcelWing
+  module Resources
+    class Automations
+      def initialize(http)
+        @http = http
+      end
+
+      def track(params)
+        response = @http.request(method: :post, path: "/api/automations/events", body: params)
+        response.fetch("data")
+      end
+    end
+  end
+end

data/lib/parcelwing/resources/contacts.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ParcelWing
+  module Resources
+    class Contacts
+      def initialize(http)
+        @http = http
+      end
+
+      def list(params = {})
+        @http.request(method: :get, path: "/api/contacts", query: params)
+      end
+
+      def create(params)
+        response = @http.request(method: :post, path: "/api/contacts", body: params)
+        response.fetch("data")
+      end
+
+      def get(id)
+        response = @http.request(method: :get, path: "/api/contacts/#{escape(id)}")
+        response.fetch("data")
+      end
+
+      def update(id, params)
+        response = @http.request(method: :patch, path: "/api/contacts/#{escape(id)}", body: params)
+        response.fetch("data")
+      end
+
+      def delete(id)
+        @http.request(method: :delete, path: "/api/contacts/#{escape(id)}")
+      end
+
+      private
+
+      def escape(value)
+        CGI.escape(value.to_s)
+      end
+    end
+  end
+end

data/lib/parcelwing/resources/emails.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ParcelWing
+  module Resources
+    class Emails
+      def initialize(http)
+        @http = http
+      end
+
+      def send(params)
+        response = @http.request(method: :post, path: "/api/emails", body: params)
+        response.fetch("data")
+      end
+    end
+  end
+end

data/lib/parcelwing/resources/segments.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ParcelWing
+  module Resources
+    class Segments
+      def initialize(http)
+        @http = http
+      end
+
+      def list(params = {})
+        @http.request(method: :get, path: "/api/segments", query: params)
+      end
+
+      def create(params)
+        response = @http.request(method: :post, path: "/api/segments", body: params)
+        response.fetch("data")
+      end
+
+      def get(id)
+        response = @http.request(method: :get, path: "/api/segments/#{escape(id)}")
+        response.fetch("data")
+      end
+
+      def update(id, params)
+        response = @http.request(method: :patch, path: "/api/segments/#{escape(id)}", body: params)
+        response.fetch("data")
+      end
+
+      def delete(id)
+        @http.request(method: :delete, path: "/api/segments/#{escape(id)}")
+      end
+
+      private
+
+      def escape(value)
+        CGI.escape(value.to_s)
+      end
+    end
+  end
+end

data/lib/parcelwing/resources/topics.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ParcelWing
+  module Resources
+    class Topics
+      def initialize(http)
+        @http = http
+      end
+
+      def list(params = {})
+        @http.request(method: :get, path: "/api/topics", query: params)
+      end
+
+      def create(params)
+        response = @http.request(method: :post, path: "/api/topics", body: params)
+        response.fetch("data")
+      end
+
+      def get(id)
+        response = @http.request(method: :get, path: "/api/topics/#{escape(id)}")
+        response.fetch("data")
+      end
+
+      def update(id, params)
+        response = @http.request(method: :patch, path: "/api/topics/#{escape(id)}", body: params)
+        response.fetch("data")
+      end
+
+      def delete(id)
+        @http.request(method: :delete, path: "/api/topics/#{escape(id)}")
+      end
+
+      private
+
+      def escape(value)
+        CGI.escape(value.to_s)
+      end
+    end
+  end
+end

data/lib/parcelwing/version.rb

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

data/lib/parcelwing.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "parcelwing/version"
+require_relative "parcelwing/error"
+require_relative "parcelwing/client"

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: parcelwing
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Parcel Wing
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Send emails and manage Parcel Wing contacts, segments, topics, and automation
+  events from Ruby.
+email:
+- support@parcelwing.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- examples/send_email.rb
+- lib/parcelwing.rb
+- lib/parcelwing/client.rb
+- lib/parcelwing/error.rb
+- lib/parcelwing/http_client.rb
+- lib/parcelwing/resources/automations.rb
+- lib/parcelwing/resources/contacts.rb
+- lib/parcelwing/resources/emails.rb
+- lib/parcelwing/resources/segments.rb
+- lib/parcelwing/resources/topics.rb
+- lib/parcelwing/version.rb
+homepage: https://github.com/parcelwing/parcelwing-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/parcelwing/parcelwing-ruby
+  source_code_uri: https://github.com/parcelwing/parcelwing-ruby
+  changelog_uri: https://github.com/parcelwing/parcelwing-ruby/releases
+  rubygems_mfa_required: 'true'
+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: 4.0.6
+specification_version: 4
+summary: Official Ruby SDK for the Parcel Wing API.
+test_files: []